Few things to consider when building an API

  • You can’t fix API after publishing
  • Well written API can mature

Pieces

There are few things to consider when building an API

  • URI
  • Verb

URI

the URI contains headers that say more about the request or response.

Verbs

verbs are what determines the response or request type being made

  • GET: used to retrieve a resource
  • POST: creating a resource
  • PUT: used to update a resource
  • PATCH: update specific items in a resource
  • Delete: remove a resource

Idempotency

Idempotency is expecting the same action from the same verbs. get should always get a resource, delete should always delete something, same as patch and put, as well as delete. Only Post isn’t idempotency, Post should always create something new.

Designing Results

  • camelCasing member name
  • Collections
    • Array
    • Show total results
    • pagination

Formatting design

format your api using headers. choose format in which the data should show

  • JSON: application/json
  • XMl: text/xml
  • JSONP: application/javascript
  • RSS

Complex scenarios

Paging

It’s a good idea to add pagination

  • Query strings for paging
  • Use wrappers to imply paging
{
totalResults: 423,
nextPage:"uri/page"
prevPage:"uri/page"
results: [
...
]
}
Error Handling

When showing errors, don’t just use status codes , you can return object with error info.

Caching

Use Etags for caching

  • if-None-Match
  • If-Match

Versioning

versioning your API is a good idea, there are several ways of versioning

  • url api/v2
  • query string ?v=20
  • using headers x-version:2.0
  • using Accept header: application/json; version=2.0

Api and Security

there are different type of securing API’s

  • Cookies
    • easy amd common
    • very easy to hack
  • Basic Auth
    • Not really secured because credentials are sent on every request
  • Token
    • more secured and simple
    • tokens are easy and expire much faster than cookies
  • OAUTH