Format of requests and responses

Requests and responses are all in JSON format, so the mimetype is application/json. Ensure that requests you make have the correct mimetype and/or content type.

Suppose we have the following Flask-SQLAlchemy models (the example works with pure SQLALchemy just the same):

from flask import Flask
from flask.ext.sqlalchemy import SQLAlchemy

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:////tmp/test.db'
db = SQLAlchemy(app)

class Person(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.Unicode, unique=True)
    birth_date = db.Column(db.Date)
    computers = db.relationship('Computer',
                                backref=db.backref('owner',
                                                   lazy='dynamic'))

class Computer(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.Unicode, unique=True)
    vendor = db.Column(db.Unicode)
    owner_id = db.Column(db.Integer, db.ForeignKey('person.id'))
    purchase_time = db.Column(db.DateTime)

Also suppose we have registered an API for these models at /api/person and /api/computer, respectively.

Note

For all requests that would return a list of results, the top-level JSON object is a mapping from "objects" to the list. JSON lists are not sent as top-level objects for security reasons. For more information, see this.

GET /api/person

Gets a list of all Person objects.

Sample response:

HTTP/1.1 200 OK

{
  "num_results": 8,
  "total_pages": 3,
  "page": 2,
  "objects": [{"id": 1, "name": "Jeffrey", "age": 24}, ...]
}
GET /api/person?q=<searchjson>

Gets a list of all Person objects which meet the criteria of the specified search. For more information on the format of the value of the q parameter, see Making search queries.

Sample response:

HTTP/1.1 200 OK

{
   "num_results": 8,
   "total_pages": 3,
   "page": 2,
   "objects": [{"id": 1, "name": "Jeffrey", "age": 24}, ...]
 }
GET /api/person/(int: id)

Gets a single instance of Person with the specified ID.

Sample response:

HTTP/1.1 200 OK

{"id": 1, "name": "Jeffrey", "age": 24}
DELETE /api/person/(int: id)

Deletes the instance of Person with the specified ID.

Sample response:

HTTP/1.1 204 No Content
POST /api/person

Creates a new person with initial attributes specified as a JSON string in the body of the request.

Sample request:

POST /api/person HTTP/1.1
Host: example.com

{"name": "Jeffrey", "age": 24}

Sample response:

HTTP/1.1 201 Created

{"id": 1}

The server will respond with 400 Bad Request if the request specifies a field which does not exist on the model.

To create a new person which includes a related list of new computer instances via a one-to-many relationship, a request must take the following form.

Sample request:

POST /api/person HTTP/1.1
Host: example.com

{
  "name": "Jeffrey",
  "age": 24,
  "computers":
    [
      {"manufacturer": "Dell", "model": "Inspiron"},
      {"manufacturer": "Apple", "model": "MacBook"},
    ]
}

Sample response:

HTTP/1.1 201 Created

{"id": 1}

Warning

The response does not denote that new instances have been created for the Computer models.

To create a new person which includes a single related new computer instance (via a one-to-one relationship), a request must take the following form.

Sample request:

POST /api/person HTTP/1.1
Host: example.com

{
  "name": "Jeffrey",
  "age": 24,
  "computer": {"manufacturer": "Dell", "model": "Inspiron"}
}

Sample response:

HTTP/1.1 201 Created

{"id": 1}

Warning

The response does not denote that a new Computer instance has been created.

To create a new person which includes a related list of existing computer instances via a one-to-many relationship, a request must take the following form.

Sample request:

POST /api/person HTTP/1.1
Host: example.com

{
  "name": "Jeffrey",
  "age": 24,
  "computers": [ {"id": 1}, {"id": 2} ]
}

Sample response:

HTTP/1.1 201 Created

{"id": 1}

To create a new person which includes a single related existing computer instance (via a one-to-one relationship), a request must take the following form.

Sample request:

POST /api/person HTTP/1.1
Host: example.com

{
  "name": "Jeffrey",
  "age": 24,
  "computer": {"id": 1}
}

Sample response:

HTTP/1.1 201 Created

{"id": 1}
PATCH /api/person?q=<searchjson>
PUT /api/person/?q=<searchjson>

Sets specified attributes on every instance of Person which meets the search criteria described in the q query parameter. PUT /api/person is an alias for PATCH /api/person, because the latter is more semantically correct but the former is part of the core HTTP standard. For more information on the format of the value of the q parameter, see Making search queries.

The response will return a JSON object which specifies the number of instances in the Person database which were modified.

Sample request:

Suppose the database contains exactly three people with the letter “y” in their names. Suppose that the client makes a request that has query parameter q set to the following JSON object (as a string):

{ "filters": [{"name": "name", "op": "like", "val": "%y%"}] }

and with the content of the request:

PATCH /api/person/1 HTTP/1.1
Host: example.com

{"age": 1}

Sample response:

HTTP/1.1 201 Created

{"num_modified": 3}
PATCH /api/person/(int: id)
PUT /api/person/(int: id)

Sets specified attributes on the instance of Person with the specified ID number. PUT /api/person/1 is an alias for PATCH /api/person/1, because the latter is more semantically correct but the former is part of the core HTTP standard.

Sample request:

PATCH /api/person/1 HTTP/1.1
Host: example.com

{"name": "Foobar"}

Sample response:

HTTP/1.1 200 OK

{"id": 1, "name": "Foobar", "age": 24}

The server will respond with 400 Bad Request if the request specifies a field which does not exist on the model.

To add a list of existing object to a one-to-many relationship, a request must take the following form.

Sample request:

PATCH /api/person/1 HTTP/1.1
Host: example.com

{ "computers":
  {
    "add": [ {"id": 1} ]
  }
}

Sample response:

HTTP/1.1 200 OK

{
  "id": 1,
  "name": "Jeffrey",
  "age": 24,
  "computers": [ {"id": 1, "manufacturer": "Dell", "model": "Inspiron"} ]
}

To add a list of new objects to a one-to-many relationship, a request must take the following form.

Sample request:

PATCH /api/person/1 HTTP/1.1
Host: example.com

{ "computers":
  {
    "add": [ {"manufacturer": "Dell", "model": "Inspiron"} ]
  }
}

Warning

The response does not denote that a new instance has been created for the Computer model.

Sample response:

HTTP/1.1 200 OK

{
  "id": 1,
  "name": "Jeffrey",
  "age": 24,
  "computers": [ {"id": 1, "manufacturer": "Dell", "model": "Inspiron"} ]
}

Similarly, to add a new or existing instance of a related model to a one-to-one relationship, a request must take the following form.

Sample request:

PATCH /api/person/1 HTTP/1.1
Host: example.com

{ "computers":
  {
    "add": {"id": 1}
  }
}

Sample response:

HTTP/1.1 200 OK

{
  "id": 1,
  "name": "Jeffrey",
  "age": 24,
  "computers": [ {"id": 1, "manufacturer": "Dell", "model": "Inspiron"} ]
}

To remove an existing object (without deleting that object from its own database) from a one-to-many relationship, a request must take the following form.

Sample request:

PATCH /api/person/1 HTTP/1.1
Host: example.com

{ "computers":
  {
    "remove": [ {"id": 2} ]
  }
}

Sample response:

HTTP/1.1 200 OK

{
  "id": 1,
  "name": "Jeffrey",
  "age": 24,
  "computers": [
    {"id": 1, "manufacturer": "Dell", "model": "Inspiron 9300"},
    {"id": 3, "manufacturer": "Apple", "model": "MacBook"}
  ]
}

To remove an existing object from a one-to-many relationship and additionally delete it from its own database, a request must take the following form.

Sample request:

PATCH /api/person/1 HTTP/1.1
Host: example.com

{ "computers":
  {
    "remove": [ {"id": 2, "__delete__": true} ]
  }
}

Warning

The response does not denote that the instance was deleted from its own database.

Sample response:

HTTP/1.1 200 OK

{
  "id": 1,
  "name": "Jeffrey",
  "age": 24,
  "computers": [
    {"id": 1, "manufacturer": "Dell", "model": "Inspiron 9300"},
    {"id": 3, "manufacturer": "Apple", "model": "MacBook"}
  ]
}

To set the value of a one-to-many relationship to contain either existing or new instances of the related model, a request must take the following form.

Sample request:

PATCH /api/person/1 HTTP/1.1
Host: example.com

{ "computers":
    [
      {"id": 1},
      {"id": 3},
      {"manufacturer": "Lenovo", "model": "ThinkPad"}
    ]
}

Sample response:

HTTP/1.1 200 OK

{
  "id": 1,
  "name": "Jeffrey",
  "age": 24,
  "computers": [
    {"id": 1, "manufacturer": "Dell", "model": "Inspiron 9300"},
    {"id": 3, "manufacturer": "Apple", "model": "MacBook"}
    {"id": 4, "manufacturer": "Lenovo", "model": "ThinkPad"}
  ]
}

Error messages

Most errors return 400 Bad Request. A bad request, for example, will receive a response like this:

HTTP/1.1 400 Bad Request

{"message": "Unable to decode data"}

Function evaluation

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.

Sample request:

GET /api/eval/person?q={"functions": [{"name": "sum", "field": "age"}, {"name": "avg", "field": "height"}]} HTTP/1.1

The format of the response is

HTTP/1.1 200 OK

{"sum__age": 100, "avg_height": 68}

If no functions are specified in the request, the response will contain the empty JSON object, {}.

Note

The functions whose names are given in the request will be evaluated using SQLAlchemy’s func object.

Example

To get the total number of rows in the query (that is, the number of instances of the requested model), use count as the name of the function to evaluate, and id for the field on which to evaluate it:

Request:

GET /api/eval/person?q={"functions": [{"name": "count", "field": "id"}]} HTTP/1.1

Response:

HTTP/1.1 200 OK

{"count__id": 5}

Table Of Contents

Related Topics

This Page