Lot of good articles were written about good design of API for external clients, but I will focus on two things which I learned:

1. api versioning for Single Page Application
2. array of objects in a response

API versioning for Single Page Application

When our API will have only one client – our front-end SPA we SHOULD NOT start path for API like /v1/articles. Why?

1. have you ever written API like /v1/articles – f so, have you ever changed it to /v2/articles?
2. when we will add /v2/articles – will /v1/articles be used by any other endpoint in our app?
3. when we will change something in /v1/articles – will SPA part stay untouched?

If you answered 3 times NO – you should think about cutting off /v1/ from your url – because probably you will never change it and there is no reason to keep it – it can be confusing for other developers.

Array of objects in a response

If you return array directly as a response you can have a headache how to extend it. Let imagine that you have response like this

[
    {name: „Inter”, points: 23},
    {name: „Milan”, points: 20},
    {name: „Rome”, points: 18}
]

Please imagine that you are developing Android app – so updating from one version to another will take some time – so you should support oldest version for some time.

Now let’s imagine that you need add some extra information for mentioned data – like title for league or how many teams will play in championships.

If your API endpoint looks like example from above in above example /v1/fixtures – you have to change it to /v2/fixtures.

BUT

If you design the response like this:

{
    data: [
        {name: „Inter”, points: 23},
        {name: „Milan”, points: 20},
        {name: „Rome”, points: 18}
    ]
}

 

You will be ready for this kind of changes.

Remember: returning directly array of objects in API for many clients is never a good solution when you are not versioning your API.