introduction to apis - what, why and how at codecore bootcamp
DESCRIPTION
The following presentation was given at CodeCore Community Week in April. You can find a full video of the presentation here: http://www.codecore.ca/apis-what-why-and-how-with-ganesh-swami-of-silota/ Whether you are building for the web, mobile, or devices yet to be invented, the enabling technology behind them are APIs. In this talk, Ganesh introduced APIs, describe what makes them possible, the process for creating APIs and supporting them. Ganesh is the founder of Silota -- a Search as a Service API. He started his programming career writing high performance algorithms for protein simulations. He likes the challenge of taking complex topics and explaining them to a beginner.TRANSCRIPT
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
Read on www.silota.com next week!
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