Specifying which fields appear in responsesΒΆ
For more information on client-side sparse fieldsets, see Sparse Fieldsets in the JSON API specification.
Warning
The server-side configuration for specifying which fields appear in resource objects as described in this section is simplistic; a better way to specify which fields are included in your responses is to use a Python object serialization library and specify custom serialization and deserialization functions as described in Custom serialization.
By default, all fields of your model will be exposed by the API. A client can
request that only certain fields appear in the resource object in a response to
a GET request by using the only
query parameter. On the
server side, you can specify which fields appear in the resource object
representation of an instance of the model by setting the only
, exclude
and additional_attributes
keyword arguments to the
APIManager.create_api()
method.
If only
is an iterable of column names or actual column attributes, only
those fields will appear in the resource object that appears in responses to
fetch instances of this model. If instead exclude
is specified, all fields
except those specified in that iterable will appear in responses. If
additional_attributes
is an iterable of column names, the values of these
attributes will also appear in the response; this is useful if you wish to see
the value of some attribute that is not a column or relationship.
Attention
The type
and id
elements will always appear in the resource object,
regardless of whether the server or the client tries to exclude them.
For example, if your models are defined like this (using Flask-SQLAlchemy):
class Person(db.Model):
id = db.Column(db.Integer, primary_key=True)
name = db.Column(db.Unicode)
birthday = db.Column(db.Date)
articles = db.relationship('Article')
# This class attribute is not a column.
foo = 'bar'
class Article(db.Model):
id = db.Column(db.Integer, primary_key=True)
author_id = db.Column(db.Integer, db.ForeignKey('person.id'))
and you want your resource objects to include only the values of the name
and birthday
columns, create your API with the following arguments:
apimanager.create_api(Person, only=['name', 'birthday'])
Now a request like
GET /api/person/1 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": {
"id": "1",
"links": {
"self": "http://example.com/api/person/1"
},
"attributes": {
"birthday": "1969-07-20",
"name": "foo"
},
"type": "person"
}
}
If you want your resource objects to exclude the birthday
and name
columns:
apimanager.create_api(Person, exclude=['name', 'birthday'])
Now the same request yields the response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"id": "1",
"links": {
"self": "http://example.com/api/person/1"
}
"relationships": {
"articles": {
"data": [],
"links": {
"related": "http://example.com/api/person/1/articles",
"self": "http://example.com/api/person/1/links/articles"
}
},
},
"type": "person"
}
}
If you want your resource objects to include the value for the class attribute
foo
:
apimanager.create_api(Person, additional_attributes=['foo'])
Now the same request yields the response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"attributes": {
"birthday": "1969-07-20",
"foo": "bar",
"name": "foo"
},
"id": "1",
"links": {
"self": "http://example.com/api/person/1"
}
"relationships": {
"articles": {
"data": [],
"links": {
"related": "http://example.com/api/person/1/articles",
"self": "http://example.com/api/person/1/links/articles"
}
}
},
"type": "person"
}
}