Adding addresses to our API Blueprint

It’s fairly common for a contact to have multiple addresses. To add addresses to our API first we’re going to need a new data structure. We’re not going to detail every endpoint for address, by now you should get the idea.

### address
- id: 101 (number, required) - The address id
- address1: 34 Barker Street (string, required) - The street name
- address2: Hogborough High (string) - Line 2 of the address
- town: Newcastle (string, required) - The address town
- county: Newcastle Upon Tyne (string, required) - The address county
- postcode: NE1 EN (string, required) - The post code

We need to amend our contact responses so that they also return any addresses for each contact, because we’re using data structures this is really easy, we just need to amend the contact data structure.

### Contact
- id: 67 (number, required) - The contact id
- firstname: Harry (string, required) - The contacts first name
- lastname: Johnson (string, required) - The contacts last name
- telephone: +44 123 123 1234 (string, required) - The contact telephone number
- email: harry.johnson@mydomain.com (string) - The contact email address
- addresses (array[Address])

Next, we’re going to add a new endpoint to allow us to add a new address to a contact, we’ll create a new group as if we were going to create a number of Address endpoints;

# Group Addresses

## Add an address to a contact [POST /contact/{id}/address]

Add an address to an existing contact.

+ Parameteter
    - id: 67 (number, required) - The id of the contact to add the address to

+ Request (application/json)
    + Headers

            client-id: JuGyFtHx8

    + Attributes
        - address1: 34 Barker Street (string, required) - The street name
        - address2: Hogborough High (string) - Line 2 of the address
        - town: Newcastle (string, required) - The address town
        - county: Newcastle Upon Tyne (string, required) - The address county
        - postcode: NE1 EN (string, required) - The post code
        - type: Home (string) - The type of address (home, work)

+ Response 200 (application/json)

    + Attributes (Contact)

+ Response 404 (application/json)

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

+ Response 400 (application/json)

        {
            "error": "Required field(s) missing."
        }

We may need to edit an address as some point too, so we need an endpoint to allow us to do that;

## Edit an existing address [PUT /contact/address{id}]

Edit an existing address.

+ Parameter
    - id: 101 (number, required) - The id of the address to modify

+ Request (application/json)
    + Headers

            client-id: JuGyFtHx8

    + Attributes
        - address1: 34 Barker Street (string, required) - The street name
        - address2: Hogborough High (string) - Line 2 of the address
        - town: Newcastle (string, required) - The address town
        - county: Newcastle Upon Tyne (string, required) - The address county
        - postcode: NE1 EN (string, required) - The post code
        - type: Home (string) - The type of address (home, work)

+ Response 200 (application/json)

    + Attributes (Contact)

+ Response 404 (application/json)

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

+ Response 400 (application/json)

        {
            "error": "Required field(s) missing."
        }

That’s our api blueprint more or less complete, I’m sure you’ll be able to add any missing endpoints yourself using what you’ve learn in this introduction to API Blueprint. Finally we can use the Aglio tool directly in the command line to generate our final HTML API documentation.

You may notice that Aglio will generate errors about the /contacts URI already being defined even though each of the end points uses different request methods (get, post, put, delete).

Comments

There are no comments, why not be the first?

Submit a reply

Your e-mail address will not be published, all fields are required.