Audio from this presentation is available at https://archive.org/details/api_design
One of the largest issues in API architecture development is that the task is often driven by the pragmatic indoctrination of a specification into a product rather than designing around the speed and ease of development, usually due to a separation between the engineering teams and their core developer user base. Extending upon the ideas of API design around developer accelerated development, we will take a deeper look into some of the great techniques delivered to us through the RESTful specification, applying them to developer API consumption practices with the intention of creating efficient best practices for rapid development. Within this talk we will explore what we have learned through reconstructing our API backbone at PayPal for our developer community, including: - API automation practices for code reduction and application longevity - Open security standards that promote developer integration ease and maintain strict security practices - RESTful API architecture best practices for developer centric accelerated development
13. Requests and Responses
GET / PUT / POST / DELETE
have specific actions
Proper status codes and error
responses
14. Don’t do This
{"error": "error 10008"}
Do This
HTTP/1.1 400 Bad Request
Content-Length: 35
{"message":"Problems parsing JSON"}
Descriptive Messaging
15. X-Rate-Limit-Limit
Number of requests allowed in current period
X-Rate-Limit-Remaining
Number of remaining requests in current period
X-Rate-Limit-Reset
Number of seconds left in current period
Useful Responses on Rate Limiting
16. Use Status Cats! http://httpcats.herokuapp.com/
Don’t Want to Use Boring Responses?
17. Allowing HTTP Overriding
curl -i -X POST
https://api.sandbox.paypal.com/v1/payments/
-H "Content-Type:application/json"
-H "X-HTTP-Method-Override: PUT"
Injecting PUT / DELETE methods when
HTTP client only supports GET / POST
20. RESTful API Core Concepts
Honor HTTP request verbs
Use proper HTTP status codes
No version numbering in URIs
Return format via HTTP Accept header
Double Rainbow: Discovery via HATEOAS
22. Uniform Interface Sub-Constraints
Resource Identification
Resources must be manipulated via
representations
Self descriptive messages
Hypermedia as the engine of
application state
25. How HATEOAS Works
curl -v -X GET
https://api.sandbox.paypal.com/v1/payments/authoriz
ation/2DC87612EK520411B
-H "Content-Type:application/json"
-H "Authorization:Bearer
ENxom5Fof1KqAffEsXtx1HTEK__KVdIsaCYF8C"
You make an API request
31. Working on the Server Side SDKs
Secure Token
Management
Simplified
Development
32. Cross Origin Issues and Options
Access to other domains / subdomains is
restricted (same origin policy)
JSONP to request resources across domains
Only supports HTTP GET requests
Cross-origin resource sharing (CORS)
Supports additional range of HTTP requests
34. How Does it Work?
OPTIONS /v1/oauth2/token HTTP/1.1
Origin: http://jcleblanc.com
Access-Control-Request-Method: PUT
Host: api.sandbox.paypal.com
Accept-Language: en-US
Connection: keep-alive
...
Site sends Origin header to server
35. How Does it Work?
Server responds with matching
Access-Control-Allow-Origin header
Access-Control-Allow-Origin: http://jcleblanc.com
Access-Control-Allow-Methods: GET, POST, PUT
Content-Type: text/html; charset=utf-8
37. The Complexities
Authentication / Authorization
Legacy API support
Working between versioning
API changes that break implementations
Reduction in latency
38. GET /payment
POST /sale
POST /payment
DELETE /refund
GET /getSinglePayment
POST /setNewSingleSale
POST /addNewSinglePayment
DELETE /issueSingleRefund
URL Structure, Verbs, and Nouns
39. Representations on Update / Create
{ "id": "PAY-17S8410768582940NKEE66EQ",
"create_time": "2013-01-31T04:12:02Z",
"update_time": "2013-01-31T04:12:04Z",
"state": "approved",
"intent": "sale",
"payer": {...},
"transactions": [{...}],
"links": [{...}] }
Send enough detail to not have to make another
request to the API
40. API architecture is all about tradeoffs
You are not making a perfect system,
you are making a perfect system for your
developers
Bringing it all Together
Heavier payloads being sent throughReduction in developer code size & scalable architecture
A lot of debate on whether versioning should go in the headers or URLhttp://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#versioninghttp://stackoverflow.com/questions/389169/best-practices-for-api-versioning
Use HTTP properly – standard request and response types
JSONP can cause XSS issues where the external site is compromised, CORS allows websites to manually parse responses to ensure security
Offload complexity to the implementing provider
Nouns are good, verbs are badhttps://blog.apigee.com/detail/restful_api_design_nouns_are_good_verbs_are_bad