Skip to content

API Endpoints

Jump to bottom
Ben Serrette edited this page Sep 16, 2019 · 32 revisions

General Notes

Return a 403 if the user performing the action does not have access to a particular data set

All endpoints should accept auth-token headers that can be validated by the authenticate-token auth endpoint

Errors (e.g. 403, 500, etc) should be accompanied by a json response body including an "error message" field

NOTE: Endpoints marked with * are not yet implemented

Authentication endpoints (Login)

All endpoints found in https://github.com/iuni-cadre/cadre-login

/api/auth/authenticate-token

  • Request:
    • Headers: 
      auth-token: token...
auth-username: username
    • Body: 
      {"username":"xxxxx"}
  • Response:
    • Headers: 
      x-cadre-auth-token
    • Body 
      {
    "user_id": ###, 
    "roles": [
        "role1",
        "role2"
    ]
}

/api/auth/logout

  • Logs user out of CADRE system (not cilogin or cognito)
  • Request:
    • Headers: 
      auth-token: token...
    • Body: 
      {"username":"xxxxx"}
  • Response:
    • 200 
      {'message': "Logout successful.", "username": "username"}
    • 422 
      {'Error': 'Logout failed.'}
    • 401 
      {'Error': 'Invalid user name provided'}
    • 500

/api/cognito/callback

  • from login.cadre.iu.edu
  • Callback from cognito for successful login

/api/cognito/logout

  • Called after /auth/logout in order to log user out of cognito

Query Builder endpoints (Data API)

Defined in middleware of https://github.com/iuni-cadre/cadre-data

/api/data/publications-async

  • Request: Same as /api/data/publications-sync
  • Response: 
    {
    "job_id": "5d4e55f7-8329-4f4f-8a08-bd762691f6d9", 
    "message_id": "1d72add8-926a-4437-878e-d7bcb3551f0d"
}

/api/data/publications-sync

  • Used for Preview queries
  • Request:
    • Headers 
      auth-token
auth-username
    • Body 
      {
    dataset: "wos", // or "mag" etc
    filters: [
        {
            field: 'year',
            value: '2007',
            operation: "AND" //or OR etc
        },
        {
            field: 'author',
            value: 'Smith',
            operation: "" 
        },
        ...
    ],
    output: [
        {
            type: 'single',
            field: 'paper_id'
        },
        {
            type: 'single',
            field: 'year'
        },
        {
            type: 'single',
            field: 'authors'
        },
        {
            type: 'network',
            field: 'citations',
            degree: '2'
        }
    ]
}
    • Response
    [
    {
        "authors_display_name": "Thomas P. Shakespeare|Val Gebski|Val Gebski|Michael J. Veness|John Simes", 
        "journal_display_name": "The Lancet", 
        "original_title": "Improving interpretation of clinical studies by use of confidence levels, clinical significance curves, and risk-benefit contours", 
        "paper_id": "2119126196", 
        "year": "2001"
    }, 
    {
        "authors_display_name": "Kobashi Yukari|Ebi Junsuke", 
        "journal_display_name": null, 
        "original_title": "ELECTRONIC DEVICE PROVIDED WITH CONTROL FUNCTION OF DIGITAL INTERFACE AND CRYPTANALYTIC FUNCTION", 
        "paper_id": "2868304693", 
        "year": "2001"
    }, 
    ...
]

RAC endpoints

These are all in the backend of the Interface Repo https://github.com/iuni-cadre/cadre-interface

/qi-api/user-jobs

  • List Jobs for the current user

/rac-api/packages/run-package

  • Runs a package by sending a job to the SQS queue
  • Request: 
    { package_id: xxx, output_filename: [xxx, xxx, ...] }
  • Response: 
    {
    "job_id": "5d4e55f7-8329-4f4f-8a08-bd762691f6d9", 
    "message_id": "1d72add8-926a-4437-878e-d7bcb3551f0d"
}
  • Error: 
    { error_message: "Descriptive Message about why it failed to run" }

/rac-api/get-packages

  • List All packages

  • GET request

  • NOTE:
    Actual response depends on how we decide to handle the database schema.

  • Request Params:

        limit: xxx,     //for pagination.  How may results to return
    page: xxx,      //for pagination. Which page are we looking at. i.e. beginning of returned set. Note:  If "start" would be easier to implement, we can do that.
    order: xxx,     //sort order of results
    search: xxx     //place holder for if we decide to implement filtering or search

  • Response:

    //will return an array of objects
[
    {
        package_id: "234221134",                
        name: "Xnet Communities Package",
        author: "CADRE Team",
        created_date: "2019-08-22 13:37:15",
        tools: [                                //Array of all tools and associated metadata.  We do not want to have to query the tool set separately
            {
                tool_id: "11234221126",
                name: "xnet2_communities",
                author: "CADRE Team",
                description: "Sends query to xnet package.",
                output_files: ["result.xnet", ...] //example filenames.  *May not be necessary in the future
            },
            ...
        ],
        input_files: ["/dataset.csv", "/dataset_edges.csv", ...]    //filenames/descriptions of packaged data sets
    },
    ....
]

  • Response Codes:

    • 200 - Success
    • 400 - malformed request (missing field, etc)
    • 401 - not logged in (request does not include auth headers)
    • 404 - query returns 0 results
    • 500 - server error

/rac-api/get-tools

  • List all tools

  • GET request

  • NOTE:
    Actual response depends on how we decide to handle the database schema. Virtually the same as the get packages endpoint.

  • Request Params:

        limit: xxx,     //for pagination.  How may results to return
    page: xxx,      //for pagination. Which page are we looking at. i.e. beginning of returned set. Note:  If "start" would be easier to implement, we can do that.
    order: xxx,     //sort order of results
    search: xxx     //place holder for if we decide to implement filtering or search

  • Response:

    //will return an array of objects
[
    {
        tool_id: "11234221126",
        name: "xnet2_communities",
        author: "CADRE Team",
        description: "Sends query to xnet package.",
        output_files: ["result.xnet", ...]   //example filenames.  *May not be necessary in the future
    },
    ...
]

  • Response Codes:

    • 200 - Success
    • 400 - malformed request (missing field, etc)
    • 401 - not logged in (request does not include auth headers)
    • 404 - query returns 0 results
    • 500 - server error

/rac-api/new-notebook/<username>

  • Create a new notebook server for a given user
  • Proxy for the Kubernates endpoint

/rac-api/notebook-status/<username>

  • Gets the status of a user's notebook
  • Proxy for the Kubernates endpoint

/rac-api/get-new-notebook-token/<username>

  • Get a new notebook token for a given user
  • Proxy for the Kubernates endpoint

/api/rac/jobs/user/{user} *

  • List jobs for specific user

/api/rac/jobs/{job_id} *

  • Get metadata including status for a specific job

/api/rac/packages/new *

  • Create a new package

/api/rac/teams *

  • List teams for current user

/api/rac/teams/{team_id} *

  • Get metadata for specific team

/api/rac/teams/new *

  • Create a new team

/api/rac/teams/user-add/<user_id> *

  • 403 if the user does not have access to the datasets used by the team
  • 404 if the user doesn't exist

/api/rac/teams/user-remove/<user_id> *

/api/rac/datasets *

  • List datasets that the current user has access to

/api/rac/notebooks *

  • List current user's available notebooks (for user and team)

/api/rac/notebooks/user/<user_id>*

  • Get specific user's notebooks

/api/rac/notebooks/team/<team_id> *

  • Get notebooks for a specific team

/api/rac/notebooks/{notebook_id}*

  • Get metadata for a specific notebook

/api/rac/data-assets/ *

  • List data assets (query results, etc) for the current user

/api/rac/data-assets/{data-set} *

  • Get list of assets for a specific data set (wos, mag, etc)

/api/rac/data-assets/{asset-id}/move-to-notebook/{notebook-id} *

  • Copy a data asset to a specific notebook.
  • Updates list of datasets that the notebook contains
  • 403 if notebook does not have access to the data set

/api/rac/institutions/ *

  • List all institutions

/api/rac/institutions/{institution} *

  • Get metadata for specific institution, including which datasets they have access to.
Clone this wiki locally