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:
-
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:
-
stop_development_server
() → None¶ Stops the development server if started in non blocking mode.
- resources (List[Resource]) – A list of
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
-
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: