Upload
lorna-mitchell
View
4.728
Download
3
Tags:
Embed Size (px)
DESCRIPTION
API Design talk from the php|tek conference in Chicago, IL
Citation preview
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/