Best Practice in API Design

About This Talk

2

• The sum of my experiences

• Building APIs

• Consuming APIs

• Maintaining my own APIs

• Contains:

• HTTP theory

• Service types and data formats

• Design pointers

When To Use An API

3

Times you want to build an API:

• To share data to another app

• To give users better control/access to their data

• To build a modular, scalable system

Web

Service

Design

Web

Request and Response

Statelessness

Status Codes

Status Codes

11

Win/Fail indicator

Status Codes

11

Win/Fail indicator Common codes:

200 OK

302 Found

301 Moved

401 Not Authorised

403 Forbidden

404 Not Found

500 Internal Server Error

Headers

HTTP Headers

13

Headers are the metadata about the content we send/receive

Useful headers:

• Accept and Content-Type: used for content format negotiation

• User-Agent: to identify what made the request

• Set-Cookie and Cookie: working with cookie data

• Authorization: controlling access

Verbs

HTTP Verbs

15

• More than GET and POST

• PUT and DELETE to update and delete in a RESTful service

• HEAD, OPTIONS and others also specified

In REST, we use:

GET Read

POST Create

PUT Update

DELETE Delete

Service

RPC Services

RPC: Remote Procedure Call

18

• Single endpoint

• Function name

• Parameters

• Return value

RPC Services

19

• XML-RPC

• JSON-RPC

• Soap

RPC Services

19

• XML-RPC

• JSON-RPC

• Soap

• other loose RPC services

JSON vs XML vs ?

JSON

21

• JavaScript Object Notation

• Lightweight

• Ideal for devices

• Native in many languages

• Great for AJAX applications

XML

22

• EXtensible Markup Lanugage

• Verbose and precise

• Best option for machine-to-machine

Soap

REST

RESTful Services

25

• REpresentational State Transfer

• URLs are unique resource identifiers

• HTTP verbs indicate which operation should happen

• We have full CRUD operations on a series of resources

Design

Target Audience

Statelessness

Version Parameter

Status Codes

Consistency

Small APIs

Heartbeat

Handling Errors

Content Negotiation

Access Control

Access Control

37

Do Not Reinvent the Wheel

• Username/password

• SSL

• Tokens

• OpenID/SAML/LDAP

Delivery and Support

Web Service Design

Thanks!

40

http://joind.in/3387

@lornajane

http://lornajane.net/