4. Web API¶

4.1. Introduction¶

Done properly, end users will never have to interact with this project at all! The functionality in this server will be exposed through an HTTP REST API. This module provides documentation for all the HTTP requests that will be handled by this API (application programming interface).

4.2. URL Endpoints¶

POST /api/v1/projects¶

Create a new project

Example Request

HTTP/1.1
Content-Type: application/json

{
    "name": "NMR Project",
    "description": "NMR Project Description",
    "owner": "mkononen"
}

Example Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "name": "NMR Project",
    "description": "NMR Project Description",
    "owner": {
        "username": "mkononen",
        "email": "my@email.com"
    }
}

Status Codes:	201 Created – Project successfully created 400 Bad Request – Unable to create project due to malformed JSON
Parameters:	session (ContextManagedSession) – The database session to be used for making the request
Return:	A Flask response
Rtype:	flask.Response

GET /api/v1/projects¶

Returns the list of projects accessible to the user

Example Response

HTTP/1.1 200 OK
Content-type: application/json
page: 1
items_per_page: 1
Count: 1

{
    "projects": [
        {
            "name": "NMR Project",
            "description": "This is a project",
            "date_created": "2015-01-01T12:00:00",
            "owner": {
                "username": "mkononen"
                "email": "my@email.com"
            }
        }
    ]
}

Status Codes:	200 OK – Request completed without errors 400 Bad Request – Bad request, occurred due to malformed JSON or due to the fact that the user was not found
Parameters:	pag_args (PaginationArgs) – A named tuple injected into the function’s arguments by the `@restful_pagination()` decorator, containing parsed parameters for pagination
Return:	A flask response object containing the required data to be displayed

POST /api/v1/users¶

Create a new user

Example Request

HTTP/1.1
Content-Type: application/json

{
    "username": "scott",
    "password": "tiger",
    "email": "scott@tiger.com"
}

Example Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "username": "scott",
    "email": "scott@tiger.com
}

Status Codes:	201 Created – The new user has been created successfully 400 Bad Request – The request could not be completed due to poor JSON 422 Unprocessable Entity – The request was correct, but the user could not be created due to the fact that a user with that username already exists
Parameters:	session (Session) – The database session that will be used to make the request

GET /api/v1/users¶

Process a GET request for the /users endpoint

Example request

GET /api/v1/users HTTP/1.1
Host: example.com
Content-Type: application/json

Example response

Vary: Accept
Content-Type: application/json

.. include:: /schemas/users/examples/get.json

Query Parameters:
	contains – A string specifying what substring should be contained in the username. Default is `''` starts_with – The substring that the username should start with. Default is `''`. page – The number of the page to be displayed. Defaults to `1`. items_per_page – The number of items to be displayed on this page of the results. Default is `1000` items.
Status Codes:	200 OK – no error
Parameters:	session (Session) – The database session used to make the request pag_args (PaginationArgs) – The pagination arguments generated by the `@restful_pagination()` decorator, injected into the function at runtime
Return:	A flask response object with the search request parsed

POST /api/v1/token¶

Generate a user’s auth token from the user in Flask’s Flask.g object, which acts as an object repository unique to each request. Expects an Authorization header with Basic Auth.

Example Request

POST /api/v1/token HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: B12kS1l2jS1=

Example Response

Content-Type: application/json

{
    "token": "a409a362-d733-11e5-b625-7e14f79230d0",
    "expiration_date": "2015-01-01T12:00:00"
}

Return:	A Flask response object with the token jsonified into ASCII

DELETE /api/v1/token¶: Revoke the current token for the user that has just authenticated, or the user with username given by a query parameter, allowed only if the user is an Administrator

GET /index¶

GET /¶

Base URL to confirm that the API actually works. Eventually, this endpoint will serve the OmicronClient. JavaScript UI to users.

Example Response

GET / HTTP/1.1
Content-Type: application/json

Hello World!

Return:	Hello, world!
Rtype:	str

GET /api/v1/users/(username_or_id)¶

Returns information for a given user

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "username": "scott"
    "email": "scott@tiger.com"
    "projects": [
        {
            "name": "NMR Experiment 1",
            "description": "Measure this thing in NMR",
            "date_created": "2015-01-01T12:00:00Z",
            "owner": {
                "username": "scott",
                "email": "scott@tiger.com"
            }
        }
    ]
}

Parameters:	session (Session) – The database session to be used in the endpoint or str username_or_id (int) – The username or user_id of the user for which data needs to be retrieved

DELETE /api/v1projects/(project_name_or_id)¶

Delete a project

Status Codes:	200 OK – The project was deleted successfully 404 Not Found – Unable to find the project to delete
Parameters:	or str project_name_or_id (int) – The project to delete

GET /api/v1projects/(project_name_or_id)¶

Returns the details for a given project

Example Response

HTTP/1.1 200 OK

{
    "name": "NMR Project",
    "description": "NMR Project Description",
    "owner": {
        "username": "mkononen",
        "email": "my@email.com"
    }
}

Status Codes:	200 OK – The Request completed successfully 404 Not Found – The request project could not be found
Parameters:	or str project_name_or_id (int) – The id or name of the project to retrieve
Return:	A flask response object containing the required data
Rtype:	`flask.Response`

GET /static/(path: filename)¶: Function used internally to send static files from the static folder to the browser.

New in version 0.5.