API Endpoints

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/packages/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 Wordcloud Package",
        type: "CADRE_DEFINED",
        description: "Generate wordcloud for all the different xnet communities"
        created_on: "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/packages/get-package/:package_id`

List a single package
GET request
The package that is returned should be the package with the url parameter package_id
Output is basically the same as /get-packages except that it returns a single object, not an array
Request Params: None

Response:

{
    package_id: "234221134",                
    name: "Xnet Communities Wordcloud Package",
    type: "CADRE_DEFINED",
    description: "Generate wordcloud for all the different xnet communities"
    created_on: "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/packages/new`

Create a new package
POST request
Notes:
- created_on should be the time at which the package is created
- created_by should be the username found in the auth-username header
- package_id should be an auto-generated serial number

Request Headers

auth-token: token...
auth-username: username

Request Params

    name: "Xnet Communities Wordcloud Package",
    description: "Generate wordcloud for all the different xnet communities",
    tools: [1234, 12345, ...],  //usually will only have 1 tool, but future proofing by accepting an array
    output_files: ["file1", "file2", ...], //default output filenames.  May not be necessary in the future
    input_files: ["archive_id1", "archive_id2", ...] //archive IDs of input data

Note: Response includes all the standard data like the get package endpoint for the newly created package

Response:

{
    package_id: "234221134",                
    name: "Xnet Communities Wordcloud Package",
    type: "CADRE_DEFINED",
    description: "Generate wordcloud for all the different xnet communities"
    created_on: "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)
- 403 - logged in but does not have permissions to create package (may not be needed until permissions are implemented)
- 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/get-tool/:tool_id`

List a single tool tools
GET request
The tool that is returned should be the tool with the url parameter tool_id
Output is basically the same as /get-tools except that it returns a single object, not an array
Request Params: None

Response:

{
    tool_id: "11234221126",
    name: "xnet2_communities",
    author: "CADRE Team",
    description: "Sends query to xnet package."
},

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/tools/new`

archives user scripts to be used with packages and generates a dockerfile for this tool
POST request
Notes:
- created_on should be the time at which the package is created
- created_by should be the username found in the auth-username header
- tool_id should be an auto-generated number
- file_paths are relative to user's home directory
- script files (file_paths) will need to be archived during tool creation
- environment is the type of dockerfile we will build, for example python for a tool written in python. This will define what command is issued to run the entry point script, as well as additional environment specific options.

Request Headers

auth-token: token...
auth-username: username

Request Params

    name: "string",
    install_commands: "string",
    description: "string",
    file_paths: [
        "/some_directory/requirements.txt",
        "/some_directory/some_script.py",
        "/some_directory/some_sub_directory",
        ....
    ],
    entrypoint: "some_script.py",
    environment: "python"

Note: Response includes the same data from the get-tool endpoint for the newly created tool

Response:

{
    tool_id: "11234221126",
    name: "tool_name",
    author: "username",
    description: "some description",
    entrypoint: "some_script.py"
    created_on: "2020-01-07 14:15:00",
},

Response Codes:
- 200 - Success
- 400 - malformed request (missing field, etc)
- 401 - not logged in (request does not include auth headers)
- 403 - logged in but does not have permissions to create tool (may not be needed until permissions are implemented)
- 500 - server error

`/rac-api/get-data-archives`

List all archived data assets
GET request

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.
    order: xxx,     //sort order of results
    search: xxx,    //place holder for if we decide to implement filtering or search,
    dataset: xxx,   //filter by specific dataset (wos, mag, pto, etc)

Response:

//will return an array of objects
[
    {
        archive_id: 123456,
        description: "Some description of the asset",
        name: "Name of the data asset",
        permissions: {},
        s3_location: "some_url", //presumedly locked down by cognito user groups
        created_on: some date,
        created_by: username
    },
    ...
]

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

`/rac-api/archive-user-file`

Move a user file to the archive so that it can be used in a package
POST request
Note: Users can only archive their own files. Usernames can be retrieved from username header.
Note: In the database, we need to record the original file path, original user,

Sample Request:

{
    file_path: "/query-results/job_id.csv",  //filepath assuming the root is the user's workspace on efs
    archive_name: "User's Query Results",
    archive_description: "Some description"
}

Sample Response:
```
{
    archive_id: xxxxx,
}
```
Response Codes:
- 200 - Success
- 400 - malformed request (file path is missing, etc)
- 404 - file does not exist
- 500 - server error

`/rac-api/user-files`

Gets list of all files/folder that a user has in his notebook. Includes package and query builder results.
GET request
Note: Only gets a single user's files based on header token
Request Params: Note

Response example:

[
    {
        path: "/query-results",
        type: "folder"
    },
    {
        path: "/query-results/JOBID1234.csv",
        type: "file",
        download_url: "https://xxxxxxxxxxx" //S3 bucket path or custom proxy url for downloading... however we decide to implement downloads
    },
    {
        path: "/query-results/JOBID2345.csv",
        type: "file",
        download_url: "https://xxxxxxxxxxx" //S3 bucket path or custom proxy url for downloading... however we decide to implement downloads
    },
    {
        path: "/packages",
        type: "folder"
    },
    ...
]

`/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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API Endpoints

General Notes

Authentication endpoints (Login)

`/api/auth/authenticate-token`

`/api/auth/logout`

`/api/cognito/callback`

`/api/cognito/logout`

Query Builder endpoints (Data API)

`/api/data/publications-async`

`/api/data/publications-sync`

RAC endpoints

`/qi-api/user-jobs`

`/rac-api/packages/run-package`

`/rac-api/packages/get-packages`

`/rac-api/packages/get-package/:package_id`

`/rac-api/packages/new`

`/rac-api/get-tools`

`/rac-api/get-tool/:tool_id`

`/rac-api/tools/new`

`/rac-api/get-data-archives`

`/rac-api/archive-user-file`

`/rac-api/user-files`

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

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

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

Clone this wiki locally