How api should look like

bad-api.md

How api should look like

Rest and http

There are some guide lines what should be done and what should not.

Last example I encountered was mixing query param with multipart body. It is even forbidden in most popular iOS network library.

Accept application/json

When creating api application/json content type should be default. Expecting it in header makes api harder to test manually.

Status codes

Inside http status 200 OK responses should have same structure. Having errors key in json under 200 OK is defiantly a bad smell.

Bad:

Status: 200 OK

{
  "response": null,
  "errors": [
    {
      "code": 409,
      "message": "User already exist"
    }
  ]
}

Good:

Status: 409 Conflict

{
  "message": "User already exist"
}

Elastic json structure

List of strings or numbers is not elastic. It should be used only in cases where we are more then confident that it will not changed.

Search

Empty results in search are not an error. Simply empty list with no elements should be returned. Not a http error. And definitely not a null. It is UI/UX job to present it in form of error if required.

Photos

Such json looks fine:

{
  "user": {
    "name": "user name",
    "photoUrl": "http://"
  }    
}

But much better would be to send photos with it's metadata

{
  "user": {
    "name": "user name",
    "photo": {
      "width": 300,
      "height": 400,
      "url": "http://"
    }
  }    
}

Fetching details

Api should respond to mobile requirements. It is technically possible to make numbers of request per screen. How ever in mobile world Internet connection is error prone. Mobiles app in case of such error should retry only failed requests.
With n requests it seems to be additional work which could be easier implemented on a backend side.