PyMacaron uses the OpenAPI format to define microservice APIs, formerly known as the swagger format.
PyMacaron relies on pymacaron-core to generate the Flask app running your microservice API.
‘pymacaron-core’ extends the OpenAPI standard with a few special attributes to bind endpoints to python methods and serialise api objects to databases.
For every API endpoint in your microservice, you need to tell PyMacaron which python method to execute. You do that with the ‘x-bind-server’ attribute. Below an example of a fictional login endpoint:
/login: post: summary: Login a user. produces: - application/json x-bind-server: myserver.handlers.do_login parameters: - in: body name: body description: User login credentials. required: true schema: $ref: "#/definitions/Credentials" responses: 200: description: API version schema: $ref: '#/definitions/Welcome' default: description: Error schema: $ref: '#/definitions/Error'
Your login method could look like:
from pymacaron_core.swagger.apipool import ApiPool from pymacaron_core.exceptions import PyMacaronCoreException def do_login(credentials): if not authenticate_user(credentials): raise PyMacaronException("Login failed") # Get the class representing bravado-core Welcome objects return ApiPool.login.model.Welcome( message="Welcome!" )
To require JWT authentication on some of your API endpoints, you need to set the ‘x-decorate-request’ and ‘x-decorate-server’ attributes for those endpoints, as described here.
PyMacaron requires that you define an Error object in your microservice API. It should look as follows:
Error: type: object description: An api error properties: status: type: integer format: int32 description: HTTP error code. error: type: string description: A unique identifier for this error. error_description: type: string description: A humanly readable error message in the user''s selected language. required: - status - error - error_description example: status: 500 error: SERVER_ERROR error_description: Expected data to send in reply but got none