apiary.apib

FORMAT: 1A

# BooksSet API
Sample REST API for books set. 

## Authentication
BooksSet API does not provide authenticated access.

## Media Types
Requests with a message-body are using plain JSON to set or update resource states.

## Error States
200 - OK, 400 - Bad Request, 500 - Internal Server Error

# BooksSet API Root [/]
BooksSet API entry point.

## Retrieve the Entry Point [GET]

+ Response 200 (application/json)

    + Body

            {
                "books": [
                    {
                        "book" : { 
                            "id":"1234", 
                            "title": "Война и мир", 
                            "author": "Л.Н. Толстой", 
                            "released": "1868"
                        }
                    }, 
                    {
                        "book" : { 
                            "id":"1235", 
                            "title":"Господин Ау", 
                            "author": "Э. Успенский",  
                            "released" : "1980"
                        }
                    }
                ]
                , "_metadata" : [
                    {
                        "totalCount":250,
                        "limit":10,
                        "offset":0
                    }
                ] 
            }
            
# Group Book
Book-related resources of *BooksSet API*.

## Book [/v1/books/{id}{?fields}]
A single Book object. The Book resource is the only resource in the BooksSet API. It represents a single book in books set.

The Book resource has the following attributes: 

- id
- title
- author
- released

The state *id* is assigned by the BooksSet API at the moment of creation. 

+ Model (application/json)

    JSON representation of Book Resource. 

    + Headers

            Link: <http:/api.booksset.com/books/1236>;rel="self"

    + Body

            {
                "id": "1236",
                "title": "Yellow mist",
                "author": "Alexander Volkov",
                "released": "1970"
            }


### Retrieve a Single Book [GET]
+ Parameters
    + id (required, number) ... numerical ID of the Book
    + fields (optional, string) ... comma separated list of required book attributes

+ Response 200

    [Book][]
    
+ Response 400

    + Body

            {"code" : 401, "message": "book wasn't found"}

### Edit a Book [PATCH]
To update a Book send a JSON with updated value for one or more of the Book resource attributes. All attributes values (states) from the previous version of this Book are carried over by default if not included in the hash.
+ Parameters
    + id (required, number) ... numerical ID of the Book

+ Request (application/json)

        {
            "released": "1970"
        }

+ Response 200
    
    [Book][]

### Delete a Book [DELETE]
+ Parameters
    + id (required, number) ... numerical ID of the Book
+ Response 204

+ Response 400

    + Body

            {"code" : 401, "message": "book wasn't found"}


## Books Collection [/v1/books{?author,title,limit,offset}]
Collection of all Books.

The Book Collection resource has the following attribute:

- total

In addition it **embeds** *Book Resources* in the BooksSet API.


+ Model (application/json)

    JSON representation of Book Collection Resource. 

    + Headers

            Link: <http:/api.booksset.com/books>;rel="self" 

    + Body

            {
                "books": [
                    {
                        "book" : { 
                            "id":"1234", 
                            "title": "Война и мир", 
                            "author": "Л.Н. Толстой", 
                            "released": "1868"
                        }
                    }, 
                    {
                        "book" : { 
                            "id":"1235", 
                            "title":"Господин Ау", 
                            "author": "Э. Успенский",  
                            "released" : "1980"
                        }
                    }
                ]
                , "_metadata" : [
                    {
                        "totalCount":250,
                        "limit":10,
                        "offset":20
                    }
                ] 
                , "_links" : [
                    {
                        "rel": "next",
                        "href": "/v1/books?offset=30&limit=10"
                    }, 
                    {
                        "rel": "prev",
                        "href": "/v1/books?offset=10"
                    }, 
                    {
                        "rel": "first",
                        "href": "/v1/books?offset=0"
                    }, 
                    {
                        "rel": "last",
                        "href": "/v1/books?offset=240"
                    } 
                ] 
            }
            
### List All Books [GET]
+ Parameters
    + offset (optional, string) ...start position in the whole list of results
    + limit (optional, string) ...limit number of results
    + author (optional, string) ...filter list by author
    + title (optional, string) ...filter list by book title

+ Response 200

    [Books Collection][]

### Create a Book [POST]

+ Request (application/json)

        {
            "title": "New book title",
            "author": "Author of new book"
        }

+ Response 201

    [Book][]