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.
3. 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!
5. What is an API?
Application Programming Interface
!
An API is the interface implemented by an
application which allows other applications to
communicate with it.
7. 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
11. What is REST?
• REpresentational State Transfer
• logical resources manipulated with HTTP verbs
• modern best practice
• wide adoption
• contrast with SOAP
14. Status Codes
2xx OK, created, all good, carry on
4xx
User error: bad API key, malformed
data, item not found, etc.
5xx Server error
15. Embrace HTTP
GET
/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
20. Best practices
security 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
21. Recap
• https + gzip + json
• use bipartite graph of nouns and verbs
• great documentation
• no surprises
26. 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