Best Practice in API Design

Best Practice in API Design

About Me

2

• Lorna Jane Mitchell

• http://lornajane.net

• PHP consultant, developer, trainer

• Author, speaker

Using APIs

3

There are various stages:

1. publish

Using APIs

3

There are various stages:

1. publish

2. dogfood

Using APIs

3

There are various stages:

1. publish

2. dogfood

3. modularity

Web

Service

Design

Web

HTTP

Request and Response

Statelessness

Status Codes

Status Codes: Headline News

12

Common codes:

200 OK

302 Found

301 Moved

401 Not Authorised

403 Forbidden

404 Not Found

500 Internal Server Error

Headers

HTTP Headers

14

Headers are the metadata about the content we send/receive

Useful headers:

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

Content Negotiation

HTTP Headers

16

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

HTTP Headers

16

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

HTTP Headers

16

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

Access Control

Verbs

HTTP Verbs

19

• 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

Target Audience

Heartbeat

RPC Services

RPC: Remote Procedure Call

24

• Single endpoint

• Function name

• Parameters

• Return value

• SOAP is a kind of RPC

Soap

Data Formats

Small APIs

REST

RESTful Services

29

• 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

Versioning

Consistency

Handling Errors

Delivery and Support

Web Service Design

Thanks!

36

https://joind.in/6385

@lornajane

http://lornajane.net/