1. OUTLINE
• What is an API?
• Why are API’s useful?
• What is HTTP? JSON? XML?
• What is a RESTful API?
• How do we consume an API?
• How do we create an API?
API’s are available from many large
websites and businesses
2. WHAT IS AN API?
• API = Application Programming Interface
• You use API’s all the time. Scanner class Java
• Web API: A set of methods exposed over the
web via HTTP to allow programmatic access to
applications.
• Allows you to quickly add functionality/data
that others have created.
• Very similar to how a web page works
3. WHY API’S ARE USEFUL
• Abstraction / DRY Principle
• Less data transfer
• Can be implemented or consumed in almost any language
• Can expose some methods to public developers
• Allows frontend developers and backend developers to agree
on a common interface
4. HTTP, JSON, XML
• Three important technologies that are often used by API’s
• HTTP: Hyper text transfer protocol, transfers data over a network
• GET : Read
• POST : Create
• PUT : Update
• PATCH : Partial Update
• DELETE : Delete
• JSON: JavaScript Object Notation, a format for data transfer
• {“key”: “value”, “key2”:{“subkey”: 2, “error”: false}}
• XML: EXtensible Markup Language: a format for data transfer
• Designed to be human and machine readable
<?PHP json_decode(‘{“key”:true}’); ?>
5. WHAT IS A RESTFUL API?
• Uniform Interface
• Resources (Nouns) URI’s that HTTP Verbs act on. The uniform interface
allows Client / Server to evolve independently.
• Stateless
• Ever have back button issues? Stateless does not care what order requests
are made in.
• Cacheable
• Client-Server
• Separation, client should not manage database, server should not manage
UI.
• Layered System
• Can uses layered system, cache, middle ware, load balancing, redundancy
etc.
https://api.example.com/v1/resource/identifier/relation?filtersortParams=value GitHub's API lets you star a gist with
PUT /gists/:id/star and unstar
with DELETE /gists/:id/star.
6. HOW TO CONSUME AN API
• Firefox: RESTClient
• Chrome: Postman
• Online: https://www.hurl.it/
• Examples:
• http://nflarrest.com/api/v1/team
• http://buscentral.herokuapp.com/suggestions POST (Feedback, message) or GET
• https://www.youtube.com/watch?v=suHY8dLKzCU
7. HOW DO DESIGN AN API
• Gather requirements from stakeholders
• Create use cases, and decide the functionality needed
• Think skeptically, make sure you explore your options
• Think ahead, make a flexible system
• Easy To learn and use, even without
documentation
• Hard to misuse
• Easy to read and maintain code that
uses it
• Sufficiently powerful to satisfy
requirements and Appropriate to
audience
• Easy to evolve (Use arrays for example)
Rules for a good API
8. CREATING A SIMPLE API
• You can use any hostable language with a HTTP library (Almost all of them)
• Decide your resources, then decide the verbs.
• Useful to wireframe the UI at this stage
• Connect to persistent data store
• Remember the principles of REST
• Example in Node.JS: https://github.com/PatrickMurphy/VoteSmart
9. ADVANCED TOPICS
• Use API Keys
• pass as a parameter
• Rate Limiting
• Headers
• X-Rate-Limit-Limit - The number of allowed requests in the
current period
• X-Rate-Limit-Remaining - The number of remaining requests
in the current period
• X-Rate-Limit-Reset - The number of seconds left in the
current period
• Authentication
• A REST API should be stateless, send auth with
every request
• Use ssl, send auth username and base64 password
over authentication header
• Caching
• HTTP Provides this!
• Last-Modified header
• Etag header, hash or checksum, If-None-Match: “etag”
• Errors
• { "code" : 1234, "message" : "Something bad happened
:(", "description" : "More details about the error here" }
• Send HTTP Status 400 level
• 401 unauthorized
• 403 forbidden
• 404 not found
• 405 method not allowed
• 410 gone (depreciated)
• 422 Unprocessable entity (validation)
• 429 Too many requests (Rate limit)