Using the API
To make requests to the API endpoints, ensure that you have gone through the Getting Connected article in this manual first. The Ellington API utilizes the following 4 parameters for content manipulation. GET, POST, PATCH, PUT, DELETE. Below we have outlined use cases using the news.story model for the 4 methods mentioned. The Ellington API uses the standard Django REST framework, so additional models will function much the same and the REST framework will alert you to any "required" fields in your endpoint requests.
GET
Examples of GET requests can also be seen by visiting http://yourdomain.com/api/docs and can be live tested using our tools. To retrieve content via the endpoint on a CURL request you either need to know the ID of the specific content you are trying to retrieve, or you can retrieve a list of content items and their associated data as in the example below
curl --location --request GET 'http://yourdomain.com/api/news/story/?limit=5' \
--header 'Authorization: Token your_stored_auth_token' \
--header 'Content-Type: application/json'In the url you can specify the following parameters:
- limit - the number of content items to return per page
- bylines - a string to match existing bylines in the Ellington admin
- offset - the initial index from which to start returning results
- ordering - a string indicating which field to use when ordering results (chronological by default)
POST
A POST via the endpoint will allow you to create new content in the database. Below is the minimum requirements to post a story via the API
curl --location --request POST 'http://yourdomain.com/api/news/story/' \
--header 'Authorization: Token your_stored_auth_token' \
--header 'Content-Type: application/json' \
--data-raw '{
"headline": "Your Story Headline",
"updated": "2020-05-05T12:00",
"pub_date": "2020-05-05T12:00",
"slug": "your-story-headline",
"tease": "Your Story Tease",
"status": 1,
"story": "This is the story body",
"categories": [12,34]
}'The status is a numerical value and applies to the story status in the admin. (Live, Draft, Deleted, Unreviewed)
- LIVE = 1
- DRAFT = 2
- DELETED = 3
- UNREVIEWED = 4
The updated and pub_date are in the ISO 8601 standard format and apply to your current timezone. I.E. YYYY-MM-DDTHH:MM
Categories are by ID only. You can find the ID of the categories in your admin by hovering the category name in the Categories app, or by clicking on the category and finding the ID in the URL, or by fetching the categories via it's corresponding API endpoint.
To POST to more fields, other than the required ones, see the model documentation in your developer docs in the admin for the field names allowed.
PATCH
A PATCH via the endpoint will allow you to update certain fields in a given content item by ID. So for instance if you are updating just the headline in a story, there is no need for the payload to contain ALL the fields of a story, you can simply do a PATCH and update just the headline.
curl --location --request PATCH 'http://yourdomain.com/api/news/story/' \
--header 'Authorization: Token your_stored_auth_token' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": 331,
"headline": "Your Updated Story Headline"
}'PUT
A PUT via the endpoint will allow you to update ALL aspects of the content item and does require ALL fields to be present in the payload.
curl --location --request PUT 'http://yourdomain.com/api/news/story/' \
--header 'Authorization: Token your_stored_auth_token' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": 331,
"headline": "Your Story Headline",
"updated": "2020-05-05T12:00",
"pub_date": "2020-05-05T12:00",
"slug": "your-story-headline",
"tease": "Your Story Tease",
"status": 1,
"story": "This is the story body",
"categories": [12,34]
}'DELETE
A DELETE via the endpoint will do exactly as expected and delete the content item in question.
curl --location --request DELETE 'http://yourdomain.com/api/news/story/' \
--header 'Authorization: Token your_stored_auth_token' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": 331
}'Be VERY careful with this permission and this method, this cannot be undone.
0 Comments
Add your comment