Requests and responses — Flask-Restless 1.0.0b2.dev documentation (original) (raw)

Requests and responses are all in the JSON API format, so each request must include an Accept header whose value is_application/vnd.api+json_ and any request that contains content must include a Content-Type header whose value is_application/vnd.api+json_. If they do not, the client will receive an error response.

This section of the documentation assumes some familiarity with the JSON API specification.

Schema at root endpoint¶

A GET request to the root endpoint responds with a valid JSON API document whose meta element contains a modelinfo object, which itself contains one member for each resource object exposed by the API. Each element in modelinfo contains information about that resource. For example, a request like

GET /api HTTP/1.1 Host: example.com Accept: application/vnd.api+json

yields the response

HTTP/1.1 200 OK Content-Type: application/vnd.api+json

{ "data": null, "jsonapi": { "version": "1.0" }, "included": [], "links": {}, "meta": { "modelinfo": { "article": { "primarykey": "id", "url": "http://example.com/api/article" }, "person": { "primarykey": "id", "url": "http://example.com/api/person" } } } }

Resource ID must be a string¶

As required by the JSON API, the ID (and type) of a resource must be a string in request and response documents. This does not mean that the primary key in the database must be a string, only that it will appear as a string in communications between the client and the server. For more information, see theIdentification section of the JSON API specification.

Trailing slashes in URLs¶

API endpoints do not have trailing slashes. A GET request to, for example, /api/person/ will result in a 404 Not Found response.

Date and time fields¶

Flask-Restless will automatically parse and convert date and time strings into the corresponding Python objects. Flask-Restless also understands intervals (also known as durations), if you specify the interval as an integer representing the number of units that the interval spans.

If you want the server to set the value of a date or time field of a model as the current time (as measured at the server), use one of the special strings"CURRENT_TIMESTAMP", "CURRENT_DATE", or "LOCALTIMESTAMP". When the server receives one of these strings in a request, it will use the corresponding SQL function to set the date or time of the field in the model.

Errors and error messages¶

Flask-Restless returns the error responses required by the JSON API specification, and most other server errors yield a400 Bad Request. Errors are included in the errors element in the top-level JSON document in the response body.

If a request triggers a sqlalchemy.exc.SQLAlchemyError (or any subclass of that exception, including DataError,IntegrityError, ProgrammingError, etc.), the session will be rolled back

JSONP callbacks¶

Flask-Restless responds to JavaScript clients that request JSONP responses. Add a callback=myfunc query parameter to the request URL on any request that yields a response that contains content (including endpoints for function evaluation; see Function evaluation) to have the JSON data of the response wrapped in the Javascript function myfunc. This can be used to circumvent some cross domain scripting security issues.

The Content-Type of a JSONP response is_application/javascript_ instead of_application/vnd.api+json_ because the payload of such a response is not valid JSON API.

For example, a request like this:

GET /api/person/1?callback=foo HTTP/1.1 Host: example.com Accept: application/vnd.api+json

will produce a response like this:

HTTP/1.1 200 OK Content-Type: application/javascript

foo({"meta": {/.../}, "data": {/.../}})

Then in your Javascript client code, write the function foo like this:

function foo(response) { var meta, data; meta = response.meta; data = response.data; // Do something cool here... }

Cross-Origin Resource Sharing (CORS) is a protocol that allows JavaScript HTTP clients to make HTTP requests across Internet domain boundaries while still protecting against cross-site scripting (XSS) attacks. If you have access to the HTTP server that serves your Flask application, I recommend configuring CORS there, since such concerns are beyond the scope of Flask-Restless. However, in case you need to support CORS at the application level, you should create a function that adds the necessary HTTP headers after the request has been processed by Flask-Restless (that is, just before the HTTP response is sent from the server to the client) using theflask.Blueprint.after_request() method:

from flask import Flask from flask_restless import APIManager

def add_cors_headers(response): response.headers['Access-Control-Allow-Origin'] = 'example.com' response.headers['Access-Control-Allow-Credentials'] = 'true' # Set whatever other headers you like... return response

app = Flask(name) manager = APIManager(app) blueprint = manager.create_api_blueprint('mypersonapi', Person) blueprint.after_request(add_cors_headers) app.register_blueprint(blueprint)