RestIt API Reference

This part of the documentation covers all the interfaces of RestIt.

Restit Application

class restit.RestItApp(resources: List[restit.resource.Resource] = None, namespaces: List[restit.namespace.Namespace] = None, debug: bool = False, raise_exceptions: bool = False, open_api_documentation: restit.open_api.open_api_documentation.OpenApiDocumentation = None)

This class represents your REST application and is used to glue everything together.

Since it is a WSGI-Application, its instance can be passed to servers like Gunicorn.

Parameters:

• resources (List[Resource]) – A list of Resource instances
• namespaces (List[Namespace]) – A list of Namespace instances
• debug (bool) – If set to True, you will get a detailed HTML stacktrace if an error is raised inside your application
• raise_exceptions (bool) – If set to True, exceptions will not cause error responses but will raise an error
• open_api_documentation (OpenApiDocumentation) – An instance of OpenApiDocumentation. If not set, no OpenApi documentation will be generated.

register_resources(resources: List[restit.resource.Resource])

Register an instance of Resource to your application.

A list of resource instances can also be set in the constructor.

set_open_api_documentation(open_api_documentation: restit.open_api.open_api_documentation.OpenApiDocumentation)

Set an instance of OpenApiDocumentation.

If not set, no OpenApi documenation will be generated.

Can also be set in the constructor.

start_development_server(host: str = None, port: int = 5000, blocking: bool = True) → int

This function starts a development server

Warning

Do not use the development server in production!

Parameters:

• host (str) – The host name, defaults to 127.0.0.1
• port (int) – The port number. If set to 0, the OS will assign a free port number for you. The port number will then be returned by that function, defaults to 5000
• blocking (bool) – If set to True, the function will block. Otherwise, the server will run in a thread and can be stopped by calling stop_development_server().

Returns:

The port the development server is running on

Return type:

int

start_development_server_in_context(host: str = None, port: int = 5000) → int

Starts a development server in a context.

Example:

import requests

from restit import RestitApp, Request, Response, Resource, request_mapping


@request_mapping("/path")
class MyResource(Resource):
    def get(self, request: Request) -> Response:
        return Response("Hello")


my_restit_app = RestitApp(resources=[MyResource()])

with my_restit_app.start_development_server_in_context(port=0) as port:
    response = requests.get(f"http://127.0.0.1:{port}/path")
    assert response.status_code == 200
    assert response.text == "Hello"

# here the development server has stopped

Parameters:

• host (str) – The host name, defaults to 127.0.0.1
• port – The port number. If set to 0, the OS will assign a free port number for you. The port number will then be returned by that function, defaults to 5000

Returns:

The port the development server is running on

Return type:

int

stop_development_server() → None

Stops the development server if started in non blocking mode.

Resource Related

class restit.Resource

Base class you have to inherit from when implementing your resource.

It provides the interface for all HTTP request methods and implicit implementation for the OPTIONS method.

If an HTTP method is not implemented but requested by the client, a MethodNotAllowed error will be raised leading to a 405 response status code on the client.

Note

You have to map your resource with an URI using the request_mapping() decorator.

restit.decorator.path(path: str, path_parameters: List[restit._path_parameter.PathParameter] = None)

Maps a resource URI path to your resource.

The path can contain multiple path parameters.

Example:

@path("/users/:id")
class UserResource(Resource):
    ...

Or:

@path("/orders/:year/:month/:id")
class OrdersResource(Resource):
    ...

Note

A specific request mapping path will always win. So given the following two paths:

• /orders/api
• /orders/:id

The incoming path /orders/api will always map to the resource with the /orders/api path.

Setting OpenApi properties

There are two ways of setting the path parameter properties for the OpenApi documentation.

1. Using the path_parameter() decorator
2. Passing a list of PathParameter instances to the path_parameter parameter of the path() decorator

Example for 2.:

from marshmallow import fields

...

@path(
    "/users/:id",
    [
        PathParameter("id", "The user id", fields.Integer())
    ]
)
class UserResource(Resource):
    ...

As you can see, we are using the marshmallow library here.

Note

If you do not describe the path parameters with either path_parameter() or inside the path() decorator, they won´t show up in the OpenApi documentation and the type is considered to be string.

Parameters:

• path (str) – The URI path to the resource
• path_parameters (List[PathParameter]) –

  Optional list of path parameter properties used to generate the OpenApi documentation. Can also be set using the path_parameter() decorator.

restit.decorator.path_parameter(name: str, description: str, field_type: marshmallow.fields.Field = <fields.String(dump_default=<marshmallow.missing>, attribute=None, validate=None, required=False, load_only=False, dump_only=False, load_default=<marshmallow.missing>, allow_none=False, error_messages={'required': 'Missing data for required field.', 'null': 'Field may not be null.', 'validator_failed': 'Invalid value.', 'invalid': 'Not a valid string.', 'invalid_utf8': 'Not a valid utf-8 string.'})>)

Decorator to describe the path parameters.

Besides describing the path parameters in the path() decorator function, you can add this decorator to your resource class.

Example:

@path("/orders/:year/:month/:id")
@path_parameter("year", "The year of the order", fields.Integer())
@path_parameter("month", "The month of the order", fields.Integer())
@path_parameter("id", "The order id", fields.Integer())
class OrdersResource(Resource):
    ...

Note

If you do not describe the path parameters with either path_parameter() or inside the path() decorator, they won´t show up in the OpenApi documentation and the type is considered to be string.

Parameters:

• name (str) – The path parameter name
• description (str) – The description of the path parameter
• field_type (marshmallow.fields.Field) – The type of the path parameter

class restit._path_parameter.PathParameter(name: str, description: str, field_type: Union[marshmallow.fields.Field, type])

Class that holds the path parameter properties and is used in the path() decorator.

Parameters:

• name (str) – The path parameter name
• description (str) – The description of the path parameter
• field_type (marshmallow.fields.Field) – The type of the path parameter

restit.decorator.query_parameter(name: str, description: str, field_type: marshmallow.fields.Field = <fields.String(dump_default=<marshmallow.missing>, attribute=None, validate=None, required=False, load_only=False, dump_only=False, load_default=<marshmallow.missing>, allow_none=False, error_messages={'required': 'Missing data for required field.', 'null': 'Field may not be null.', 'validator_failed': 'Invalid value.', 'invalid': 'Not a valid string.', 'invalid_utf8': 'Not a valid utf-8 string.'})>)

restit.decorator.request_body(content_types: Dict[str, Union[marshmallow.schema.Schema, marshmallow.fields.Field]], description: str, required: bool = True, validation_error_class=<class 'restit.exception.client_errors_4xx.UnprocessableEntity'>)

Describe an expected request body for a method

Parameters:

• content_types (Dict[str, Union[marshmallow.Schema, marshmallow.fields.Field]) – A dictionary that maps a Content-Type with a marshmallow schema or a field.
• description (str) – The description of the request body
• required (bool) – Is the request body required?
• validation_error_class (An instance of type Exception) – An error class either that should be raised if either the schema validation fails or the request body is missing.

OpenApi Documentation

class restit.open_api.OpenApiDocumentation(info: restit.open_api.info_object.InfoObject, path: str = '/api')

Class that that is responsible for creating the OpenApi documentation.

If you want to create a OpenApi documentation, you have to instantiate this class and pass it your RestItApp.

Example:

from restit import RestItApp
from restit.open_api import OpenApiDocumentation, InfoObject, ContactObject, LicenseObject

open_api_documentation = OpenApiDocumentation(
    info=InfoObject(
        title="First OpenApi Test",
        description="Super description",
        version="1.2.3",
        contact=ContactObject("API Support", "http://www.example.com/support", "support@example.com"),
        license=LicenseObject("Apache 2.0", "https://www.apache.org/licenses/LICENSE-2.0.html"),
        terms_of_service="http://example.com/terms/"
    ),
    path="/some/custom/api/path"
)

restit_app = RestItApp(resource=[...], open_api_documentation=open_api_documentation)

...

Once your app is running, you can access http://<host>:<port>/some/custom/api/path/ to see your API documentation.

Parameters:

• info (InfoObject) – Metadata about the API
• path (str) – The path where the API is served

generate_spec

Generate the OpenApi specification as a dictionary

Note

Only use this function if you want to generate the API specification outside your app.

Returns:The generated specification Return type:dict

register_resource(resource: restit.resource.Resource)

Register a resource that should be documented.

Note

Only use this function if you want to generate the API specification outside your app.

Parameters:resource (Resource) – The resource that should be registered

class restit.open_api.InfoObject(title: str, version: str, description: str = None, terms_of_service: str = None, contact: restit.open_api.contact_object.ContactObject = None, license: restit.open_api.license_object.LicenseObject = None)

Holds the OpenApi documentation InfoObject.

The object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.

Parameters:

• title (str) – The title of the API
• version (str) – The version of the OpenAPI document
• description (str) – A short description of the API. CommonMark syntax MAY be used for rich text representation
• terms_of_service (str) – A URL to the Terms of Service for the API. MUST be in the format of a URL
• contact (ContactObject) – The contact information for the exposed API
• license (LicenseObject) – The license information for the exposed API

class restit.open_api.LicenseObject(name: str, url: str = None)

License information for the exposed API.

Parameters:

• name (str) – The license name used for the API
• url (str) – A URL to the license used for the API. MUST be in the format of a URL

class restit.open_api.ContactObject(name: str, url: str, email: str)

Contact information for the exposed API.

Parameters:

• name (str) – The identifying name of the contact person/organization
• url (str) – The URL pointing to the contact information. MUST be in the format of a URL
• email (str) – The email address of the contact person/organization. MUST be in the format of an email address