Read API
The Read API is available by adding /api to the URL of your Interface instance. To access the API for a particular Model, such as a Blog, you would use the URL:
/api/blog
By default this will return all content items in the Blog model, in XML format (make sure you have enabled “Read API” access for your Blog model). To return the data in JSON, you just add .json to the end of the URL:
/api/blog.json
Adding .xml to the end will have the same output as no extension at all.
Naming Conventions
For standardization, we recommend accessing all Models in their singular, lower-case form: e.g. /api/blog.xml instead of /api/Blog.xml or /api/blogs.xml. If your Model name contains two or more words, such as MyCategory, use all lower-case add an underscore between each word:
/api/my_category
When referring to Associations, you must use the correct plural or singular form of the Association. Some examples:
| Relationship | Reference Format |
|---|---|
| BlogEntry has_many Comment | comments |
| Comment belongs_to BlogEntry | blog |
| BlogEntry belongs_to Category | category |
| Category has_many BlogEntry | blog_entries |
| BlogEntry has_and_belongs_to_many Category | categories |
| Category has_and_belongs_to_many BlogEntry | blog_entries |
Filtering and Sorting Results
The API allows for some basic filtering and sorting of results. Below is a list of query string parameters that can be passed in with your API call to modify the results:
| Parameter | Description |
|---|---|
| order_by | Which field in the model to order your results by. Defaults to id |
| order | Which order to return results with, either asc or desc. Defaults to asc |
| limit | Limit results to the number specified. Defaults to unlimited. |
| offset | Offset results to the number specified. |
| include | Include content from relationships. To specify multiple relationships, separate them with a comma. See more about include below. |
| fields | Only return specified fields. To specify multiple fields, separate them with a comma. |
| break | Format text field types with p and break tags. Possible values are true or false. |
| result | What type of result to return, either list (default) or count, which returns a count of all objects returned in your query. |
| search (formerly logic) | Pass in a formatted search string using our custom Search Language. In previous Interface versions, this is known as logic, and is kept in for backwards compatibility. |
Including Related Content in Your Query
In your API call, you can include any arbitrary content through an Association the particular Model has. This brings in the related content inline with your results, which could save you from having to make multiple API calls to get additional content.
For instance, if your BlogEntry has_many Comment, you could include your comments inline with this API call:
/api/blog_entry.xml?include=comments
If you wanted to do an API call for Comments and include each Comment’s Blog (the reverse what the previous example):
/api/comment.xml?include=blog
To include multiple Associations, separate them with a comma. If your BlogEntry has_many Comment and also belongs_to Category:
/api/blog_entry.xml?include=comments,category