Customizing the ReSTful interface

HTTP methods

By default, the APIManager.create_api() method creates a read-only interface; requests with HTTP methods other than GET will cause a response with 405 Method Not Allowed. To explicitly specify which methods should be allowed for the endpoint, pass a list as the value of keyword argument methods:

apimanager.create_api(Person, methods=['GET', 'POST', 'DELETE'])

This creates an endpoint at /api/person which responds to GET, POST, and DELETE methods, but not to other ones like PUT or PATCH.

The recognized HTTP methods and their semantics are described below (assuming you have created an API for an entity Person). All endpoints which respond with data respond with serialized JSON strings.

GET /api/person

Returns a list of all Person instances.

GET /api/person/(int: id)

Returns a single Person instance with the given id.

GET /api/person?q=<searchjson>

Returns a list of all Person instances which match the search query specified in the query parameter q. For more information on searching, see Making search queries.

DELETE /api/person/(int: id)

Deletes the person with the given id and returns 204 No Content.

POST /api/person

Creates a new person in the database and returns its id. The initial attributes of the Person are read as JSON from the body of the request. For information about the format of this request, see Format of requests and responses.

PATCH /api/person/(int: id)

Updates the attributes of the Person with the given id. The attributes are read as JSON from the body of the request. For information about the format of this request, see Format of requests and responses.

PATCH /api/person?q=<searchjson>

This is only available if the allow_patch_many keyword argument is set to True when calling the create_api() method. For more information, see Enabling patching the result of a search.

Updates the attributes of all Person instances which match the search query specified in the query parameter q. The attributes are read as JSON from the body of the request. For information about searching, see Search Page. For information about the format of this request, see Format of requests and responses.

PUT /api/person?q=<searchjson>

PUT /api/person/(int: id)

Aliases for PATCH /api/person.

API prefix

To create an API at a different prefix, use the url_prefix keyword argument:

apimanager.create_api(Person, url_prefix='/api/v2')

Then your API for Person will be available at /api/v2/person.

Collection name

By default, the name of the collection in the API will be the lowercase name of the model. To provide a different name for the model, provide a string to the collection_name keyword argument of the APIManager.create_api() method:

apimanager.create_api(Person, collection_name='people')

Then the API will be exposed at /api/people instead of /api/person.

Enabling patching the result of a search

By default, a PATCH /api/people request (with or without a q query parameter) will cause a 405 Method Not Allowed response. By setting the allow_patch_many keyword argument of the APIManager.create_api() method to be True, PATCH /api/person requests will patch the provided attributes on all of the instances of Person which match the provided search query (or all instances if no query parameter is provided):

apimanager.create_api(Person, allow_patch_many=True)

Exposing evaluation of SQL function

If the allow_functions keyword argument is set to True when creating an API for a model using APIManager.create_api(), then an endpoint will be made available for GET /api/eval/person which responds to requests for evaluation of functions on all instances the model.

For information about the request and response formats for this endpoint, see Function evaluation.

Requiring authentication for some methods

Note

The authentication system in Flask-Restless is relatively simple, but since I suspect it is a common requirement for ReSTful APIs, suggestions, comments, and pull requests are much appreciated. Please visit our issue tracker.

If you want certain HTTP methods to require authentication, use the authentication_required_for and authentication_function keyword arguments to the APIManager.create_api() method. If you specify the former, you must also specify the latter.

authentication_required_for is the list of HTTP method names which will require authentication and authentication_function is a function with zero arguments which returns True if and only if the client making the request has been authenticated. This function can really be anything you like, but presumably it will have something to do with your authentication framework.

For an example using Flask-Login, see the examples/authentication directory in the source distribution, or view it online at GitHub.