This document provides an overview of APIs, including what they are, why they are useful, common data formats like JSON and XML, RESTful API design principles, and how to consume and create APIs. It discusses topics like HTTP verbs, resources and URIs, caching, authentication, and error handling for APIs. The document also provides examples of consuming APIs through tools like Postman and creating a simple API in Node.js.

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)