API Blueprint for Laravel API 101 - DOCUMENT lesson

articles.apib

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
        }