apiary.apib

FORMAT: 1A
HOST: http://contactbooster-rails.herokuapp.com/

# contactbooster/rails
API using rails-api for contactbooster app.

# status code
```200``` successfull request with body returned

```201``` successfull creation request with body returned

```204``` successfull request with nothing returned

```400``` bad request (input, validations, parameters...)

```404``` resource(s) not found

# endpoints documentation

# Group List
## List [/lists/{id}]
A single List object with all its contacts

+ Model (application/json; charset=utf-8)

        {
          "id": 1,
          "name": "Friends",
          "position": 0
        }

+ Parameters
    + id (required, number, `1`) ... Numeric `id` of the List to perform action with

### Retrieve a List [GET]
+ Response 200 (application/json; charset=utf-8)

          {
            "id": 1,
            "name": "Friends",
            "position": 0,
            "contacts": [
              { "id": 1, "firstname": "Michael", "lastname": "Jordan", "phone": "555533331", "list_id", 1 },
              { "id": 2, "firstname": "Scottie", "lastname": "Pippen", "phone": "222244444, "list_id", 1" }
            ]
          }

### Remove a List [DELETE]
+ Response 204

+ Response 404 (application/json; charset=utf-8)

        {
          "error": "resource not found."
        }


### Update a List [PATCH]

+ Request (application/json; charset=utf-8)

        {
            "list": { "name": "Work", "position": 1 }
        }

+ Response 200 (application/json; charset=utf-8)

        {
            "id": 2,
            "name": "Work",
            "position": 1
        }

+ Response 404 (application/json; charset=utf-8)

        {
          "error": "resource not found."
        }


## Lists Collection [/lists]
+ Model (application/json; charset=utf-8)

        {
          "total": 2,
          "lists":
          [
            {
              "id": 1,
              "name": "friends",
              "position": 0,
              "contacts": [
                { "id": 1, "firstname": "Joey", "lastname": "Tribianni", "phone": "555533331" }
              ]
            },
            {
              "id": 2,
              "name": "family",
              "position": 1,
              "contacts": [
                { "id": 2, "firstname": "Michel", "lastname": "Platini", "phone": "555533331" },
                { "id": 3, "firstname": "Jean pierre", "lastname": "Papin", "phone": "555533331" }
              ]
            }
          ]
        }

### List all Lists [GET]
+ Response 200 (application/json; charset=utf-8)

    [Lists Collection][]

### Create a List [POST]
+ Request (application/json; charset=utf-8)

        {
            "list": {
              "name": "Friends",
              "position": 0
            }
        }

+ Response 201 (application/json; charset=utf-8)

    [List][]

# Group Contact

## Contact [/lists/{list_id}/contacts/{contact_id}]

+ Model (application/json; charset=utf-8)

        {
            "id": 1,
            "list_id": 1,
            "lastname": "Hawk",
            "firstname": "Tony",
            "phone": "55544433322"
        }

+ Parameters
    + list_id (required, number, `1`) ... Numeric `id` of the List to perform action with.
    + contact_id (required, number, `1`) ... Numeric `id` of the contact to perform action with. Has example value.

### Retrieve a contact [GET]

+ Response 200 (application/json; charset=utf-8)

    [Contact][]

+ Response 404 (application/json; charset=utf-8)

        {
          "error": "resource not found."
        }

### Delete a contact [DELETE]
+ Response 204

+ Response 404 (application/json; charset=utf-8)

        {
            "error": "resource not found."
        }

### Update a contact [PATCH]
+ Request (application/json; charset=utf-8)

        {
            "contact": { "lastname": "Guez" }
        }

+ Response 200 (application/json; charset=utf-8)

        {
            "id": 1,
            "list_id": 1,
            "lastname": "Guez",
            "firstname": "Tony",
            "phone": "55544433322"
        }

+ Response 400 (application/json; charset=utf-8)

        {
            "phone": "Invalid phone format.",
            "lastname": "Lastname should have a length between 2 and 20 characters.",
            "firstname": "Firstname should have a length between 2 and 20 characters."
        }

+ Response 404 (application/json; charset=utf-8)

        {
            "error": "resource not found."
        }


## Contacts Collection [/lists/{list_id}/contacts]

+ Parameters
    + list_id (required, number, `1`) ... Numeric `id` of the List to perform action with.

+ Model (application/json; charset=utf-8)

        [{
          "id": 1,
          "list_id": 1,
          "lastname": "Jordan",
          "firstname": "Michael",
          "phone": "5555544444"
        },
        {
          "id": 1,
          "list_id": 1,
          "lastname": "Pippen",
          "firstname": "Scottie",
          "phone": "66666666"
        }]

### List all Contacts [GET]
+ Response 200 (application/json; charset=utf-8)

    [Contacts Collection][]

### Create a contact [POST]
+ Request (application/json; charset=utf-8)

        {
            "contact" : {
              "lastname": "Hawk",
              "list_id": 1,
              "firstname": "Tony",
              "phone": "55544433322"
            }
        }

+ Response 201 (application/json; charset=utf-8)

    [Contact][]