/learn-api-design

:innocent: Essential learning for people building APIs

Learn API Design contributions welcome

Essential learning for people building an API

Grandma Remote

Joking aside, starting a project "from scratch" is a opportunity (and privilege) few people get.
If you are fortunate enough to be in that position, do not take the task lightly.

golden ticket

Building the interface for a new project is nothing short of a Golden Ticket! So do your homework before you start!

Intro

Having a great API will make or break your project/product.

A few quotes from Joshua Bloch's Google Talk on "How To Design A Good API and Why it Matters"
and Kevin Lacker's (@Parse) "How to Design Great APIs"

"You have one chance to get it right." 3:17

"A bad API can be among a company's greatest liabilities... can cause an un-ending stream of support phonecalls ... and it can inhibit a company's ability to move forward" 2:51

"Once you have a bad API, you can't change it, you are pretty much stuck with it forever." 3:12

" ... A good API needs to appeal to the most powerful emotion: Laziness". 3:23

"You need to be opinionated even when there is no right and wrong" 31:02

"Always make your REST API as small/short as possible" 31:19

Characteristics of a Good API

  • Easy to learn (notice the priority placement of learn-ability...)
  • Intuitive / Easy to use even without documentation
  • Hard to misuse (write tests for "undesirable" behaviour)
  • Easy to read and maintain code that uses it
  • Sufficiently powerful to satisfy requirements
  • Easy to evolve (the simpler the initial API the easier it will be to extend)
  • Appropriate to audience (make it beginner friendly...)
  • Opinionated (means people don't have to think)

Types of API

REST

Representational State Transfer (REST) is a software architecture style consisting of guidelines and best practices for creating scalable web services.

What is a RESTful web service?

restful API

ReST is a structured way of building web services and applications. When something is described as "RESTful" it simply means it follows a predefined predictable pattern for how it responds to requests.

Video Explanation of REST

Read more about REST APIs / RESTful Web Services

Why REST?

  • Scalability (dissemination - more people use your API)
  • Generality
  • Independence
  • Latency (Caching)
  • Security
  • Encapsulation

Verbs

  • GET = read an existing record or collection (list of records)
  • POST = create and partial update.
  • PUT = create and idempotent update (always send all the fields required - not partial update)
  • DELETE = does exactly what it says
Examples
  • GET /comment - Returns a list of all comments
  • GET /comment/:id - Returns a comment with the given id
  • POST /comment - Creates a new comment
  • PUT /comment/:id - Updates a comment with the given id
  • DELETE /comment/:id - Deletes a comment with the given id

Tips

To reduce the amount of data retrieved, we can specify the exact fields we want in url e.g:

GET /accounts/1234/fields=firstname,surname,etc

see: 52:29

Reading / Watching

Examples of Successful (Good) APIs

Useful Resources

Streaming

WebSockets

Reading

Examples

Versioning your API?

API Versioning

There is on-going debate on whether APIs should be versioned and if so, how should this be done.

There are two primary approaches to versioning 32:43

Intro Reading

Wrong way 1 – URL versioning

HTTP GET:
https://haveibeenpwned.com/api/v2/breachedaccount/foo

Wrong way 2 - custom request header

HTTP GET:
https://haveibeenpwned.com/api/breachedaccount/foo
api-version: 2

Wrong way 3 - content type

HTTP GET:
https://haveibeenpwned.com/api/breachedaccount/foo
Accept: application/vnd.haveibeenpwned.v2+json

Further Reading (Versioning)

Caching

General Background Reading + Watching