Date post: | 06-May-2015 |
Category: |
Technology |
Upload: | codecore |
View: | 637 times |
Download: | 0 times |
Introduction to APIsCodeCore Community Week
April 25, 2014
Ganesh Swamiwww.silota.com
Hi
• Programming professionally for 10+ years
• x86 assembly, STL, boost, python-boost, python
SILOTA• Search As A Service
• full stack: crawling, indexing, retrieving, tag deployment
• First class developer experience (DX)
• documentation
• testing
• sandbox
• 800+ search engines in production!
APIs: What & Why
What is an API?Application Programming Interface
!An API is the interface implemented by an
application which allows other applications to communicate with it.
What is an API?
communicate
Why build an API?
• explosion of devices connected to the internet
• can be a company’s greatest asset
• bizdev 2.0: internal developers, consultants, partners, customers
Sample APIs• aws
• dropbox
• github
• stripe
• salesforce
• twillio
• …
Source: Mary Meeker’s Internet Trends 2013
APIs: How
What is REST?• REpresentational State Transfer
• logical resources manipulated with HTTP verbs
• modern best practice
• wide adoption
• contrast with SOAP
HTTP Clients
Request Response
GET /simtec/httpgallery/introduction/ HTTP/1.1 Accept:*/* Accept-‐Language: en-‐gb Accept-‐Encoding: gzip, deflate User-‐Agent: Mozilla/4.0 (compatible; MSIE 6.0) Host: www.httpwatch.com Connection: Keep-‐Alive !!!!!
HTTP/1.1 200 OK Server: Microsoft-‐IIS/5.1 Date: Mon, 04 Oct 2004 12:04:43 GMT X-‐Powered-‐By: ASP.NET X-‐AspNet-‐Version: 1.1.4322 Cache-‐Control: no-‐cache Pragma: no-‐cache Expires: -‐1 Content-‐Type: text/html; charset=utf-‐8 Content-‐Length: 8307 !<html> <head> ...
HTTP Verbs
• GET, POST, PUT, PATCH, DELETE
Status Codes
2xx OK, created, all good, carry on
4xx User error: bad API key, malformed data, item not found, etc.
5xx Server error
Embrace HTTPGET /document Retrieve all documents
GET /document/19 Retrieve a specific document #19
POST /document Create a new document
PUT /document/19 Update an existing document #19
DELETE /document/19 Delete an existing document #19
Postman: Chrome Extension
Bipartite graph/documents /documents/:id …
GET
POST error
PUT error
PATCH error
DELETE
Best practicessecurity
base URLs
serialization
timestamps
versioning
caching
gzip
logging
Best practicessecurity https all the way
base URLs api.companyname.com
serialization json
timestamps ISO 8601 & UTC
versioning /v1/
caching ETag & Last-Modified
gzip always & pretty print responses
logging if possible
Recap
• https + gzip + json
• use bipartite graph of nouns and verbs
• great documentation
• no surprises
Integration Challenges
Handling Timeouts
The Pitch
BENEFITSCOSTS
What We Give (investment)
What We Get (return)
References• How to Design a Good API and Why it Matters:
• http://lcsd05.cs.tamu.edu/slides/keynote.pdf
• Best Practices for Designing a Pragmatic RESTful API
• http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
• REST worst practices:
• http://jacobian.org/writing/rest-worst-practices/
• Building RESTful APIs: http://www.slideshare.net/silota/building-restful-apis