5.1.3. API Views

5.1.3.1. Schema-defined Resource

class views.schema_defined_resource.SchemaDefinedResource

Abstract class that defines an API view with a schema built into it. This class is capable of serving its schema and

is_schema_draft3

Checks if self.schema corresponds to the Draft 3 JSON Schema

Note

At the time of writing, the latest draft of JSON Schema is Draft 4. Refrain from using Draft 3 schemas in this API wherever possible

Returns:True if the schema conforms to draft 3, else false Return type:bool

schema

Return the JSON schema of the view as a dictionary

validate(dict_to_validate, source_dict=None)

Checks that the supplied dictionary matches the JSON Schema in another dictionary. If no source_dict is provided, the method will attempt to validate the validation dictionary against attr:self.schema.

Parameters:

• dict_to_validate (dict) – The dictionary representing the JSON against the JSON Schema to be validated
• source_dict – The dictionary representing the JSON Schema against which the incoming JSON will be compared

Returns:

A tuple containing a boolean corresponding to whether the schema validated or not, and a message. If the schema validated successfully, the message will be "success". If not, then the message will correspond to the reason why the schema did not successfully validate

5.1.3.2. Projects

class views.projects.ProjectContainer

Maps the /projects endpoint

get(*args, **kwargs)

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"
            }
        }
    ]
}

Statuscode 200:Request completed without errors Statuscode 400: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 Returns:A flask response object containing the required data to be displayed

post(*args, **kwargs)

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"
    }
}

Statuscode 201:Project successfully created Statuscode 400:Unable to create project due to malformed JSON Parameters:session (ContextManagedSession) – The database session to be used for making the request Returns:A Flask response Return type:flask.Response

class views.projects.Projects

Maps the “/projects/<project_id>” endpoint

exception ProjectNotFoundError

Thrown if __getitem__ cannot find the required project

__weakref__

list of weak references to the object (if defined)

Projects.__delitem__(*args, **kwargs)

Retrieve the required project name or ID corresponding r

Parameters:

• session (ContextManagedSession) – The database session that this method will use to communicate with the database
• project_name_or_id (str) – The project name or ID that will be used as the key to find the project

Projects.__getitem__(*args, **kwargs)

Return the project corresponding to the name or ID

Parameters:

• session (ContextManagedSession) – The database session to be used for making the request. This is injected into the method using the @database_session() decorator
• project_name_or_id (str) – The project name or the project ID

Returns:

The project model class from the database

Return type:

database.models.projects.Project

Raises:

Projects.ProjectNotFoundError if the project is not found in the DB

Projects.delete(*args, **kwargs)

Delete a project

Statuscode 200:The project was deleted successfully Statuscode 404:Unable to find the project to delete Parameters:or str project_name_or_id (int) – The project to delete

Projects.get(*args, **kwargs)

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"
    }
}

Statuscode 200:The Request completed successfully Statuscode 404:The request project could not be found Parameters:or str project_name_or_id (int) – The id or name of the project to retrieve Returns:A flask response object containing the required data Return type:flask.Response

5.1.3.3. Users

Contains views for the /users endpoint.

class views.users.UserContainer

Maps the /users endpoint’s GET and POST requests, allowing API consumers to create new users

get(*args, **kwargs)

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 contains:

A string specifying what substring should be contained in the username. Default is ''

Query starts_with:  

The substring that the username should start with. Default is ''.

Query page:

The number of the page to be displayed. Defaults to 1.

Query items_per_page:  

The number of items to be displayed on this page of the results. Default is 1000 items.

Statuscode 200:

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

Returns:

A flask response object with the search request parsed

static parse_search_query_params(request)

This method enables text search over the results returned by a GET request on the /users endpoint. It parses query parameters from Flask.request, a container for the HTTP request sent into the method. Currently, the query parameters parsed here are

• starts_with: A string stating what the username should begin with
• contains: A string specifiying what the username should contain
• ends_with: A string stating what the username should end with

Parameters:request – The flask request from which query parameters need to be retrieved Returns:A % delineated search string ready for insertion as a parameter into a SQL or SQLAlchemy query language’s LIKE clause

post(*args, **kwargs)

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
}

Statuscode 201:The new user has been created successfully Statuscode 400:The request could not be completed due to poor JSON Statuscode 422: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

class views.users.UserView

Maps the /users/<username> endpoint

get(*args, **kwargs)

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