Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
API Blueprint for Laravel API 101 - DOCUMENT lesson
FORMAT: 1A
# Articles
Simple API for managing news articles.
## Authorization
To create, update or destroy an article, you have to authorize. To authorize you have to send your personal `api_token` key with the request in one of these three possible ways:
### Query parameter
Append `?api_token=<your_token_here>` to the end of the URL `POST /api/v1/articles`.
### Request body
To the body of the request, along with other data like `heading` and `content`, pass `api_token` with the value of your token. Be sure to use `x-www-form-urlencoded` in Postman.
### Header Authorization Bearer
Add a header to the request for `Authorization:Bearer <your_token_here>`.
In Postman click on Headers tab and start typing in key field `Authorization`, a drop-down will show so that you can select it. In value field type `Bearer <your_token_here>`. Be sure to replace `<your_token_here>` with the actual token you got from seeding the user.
## Group Articles
### Article Collection [/api/v1/articles{?include}]
This resource allows you to view a list of articles and create a new article.
#### View all articles [GET]
This actions returns all articles in JSON format with tags.
By default it does not return the article category.
You have to ask for it specifically by using `&include=category`.
+ Parameters
+ include (optional, string) - Items that should be included in the result. Can be: category.
+ Response 200 (application/json)
{
"data": [
{
"id": 1,
"heading": "Et magni quam necessitatibus.",
"content": "Tenetur qui corporis blanditiis non ipsam aliquid. Sunt autem qui unde modi molestias. Nam vel rerum minima similique impedit voluptates voluptatum sit.",
"published": true,
"published_at": "12.03.1977",
"tags": {
"data": [
{
"name": "dolores"
},
{
"name": "nihil"
},
{
"name": "maxime"
}
]
}
},
{
"id": 2,
"heading": "Blanditiis ea dignissimos rerum at enim.",
"content": "Est numquam quos architecto minus. Aut voluptatem porro explicabo quidem ipsum quas. Dignissimos non voluptatem atque. Aut ea neque aperiam non numquam vero dolores.",
"published": true,
"published_at": "12.11.1998",
"tags": {
"data": []
}
}
]
}
#### Create a new article [POST]
You may create a new article using this action. **This action requires authentication.**
+ heading (string, required) - Article title.
+ content (text, required) - Article content.
+ category_id (number, required) - ID of the category to which the article belongs.
+ published_at (date) - DateTime when the article is published `2017-03-19 20:47:00`.
+ published (boolean) - Indicates if the article is published `1` or `0`.
+ Request (application/json)
+ Headers
Authorization: Bearer your-token-here
+ Body
{
"heading": "How to win the lottery",
"content": "Wouldn't you like to know ;)",
}
+ Response 201 (application/json)
{
"message": "Created",
"status_code": 201
}
### Article [/api/v1/articles/{article_id}{?include}]
This resource allows you to view a single article, update an article or destroy an article.
+ Parameters
+ article_id (string) - The ID of the article on which you want to do actions on.
#### View a single article [GET]
If you want to fetch data for a single article this is what you will want to use.
+ Parameters
+ include (optional, string) - Items that should be included in the result. Can be: category.
+ Response 200 (application/json)
{
"data": [
{
"id": 1,
"heading": "Et magni quam necessitatibus.",
"content": "Tenetur qui corporis blanditiis non ipsam aliquid. Sunt autem qui unde modi molestias. Nam vel rerum minima similique impedit voluptates voluptatum sit.",
"published": true,
"published_at": "12.03.1977",
"tags": {
"data": [
{
"name": "dolores"
},
{
"name": "nihil"
},
{
"name": "maxime"
}
]
}
}
]
}
#### Update an existing article [PUT]
This action enables you to update an existing article. **This action requires authentication.**
You can send all parameters in the request body or just the paramenters that you want to change.
+ heading (string) - Article title.
+ content (text) - Article content.
+ category_id (number, required) - ID of the category to which the article belongs.
+ published_at (date) - DateTime when the article is published `2017-03-19 20:47:00`.
+ published (boolean) - Indicates if the article is published `1` or `0`.
+ Request (application/json)
+ Headers
Authorization: Bearer your-token-here
+ Body
{
"category_id": "2"
}
+ Response 202 (application/json)
{
"message": "Updated",
"status_code": 202
}
#### Delete an existing article [DELETE]
This action enables you to delete an existing article. **This action requires authentication.**
+ Request (application/json)
+ Headers
Authorization: Bearer your-token-here
+ Response 202 (application/json)
{
"message": "OK",
"status_code": 200
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment