API Crash Course
CWU Startup Club
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
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
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
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}’); ?>
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.
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
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
Rules for a good API
• 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)
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
ADVANCED TOPICS
• Use API Keys
•
pass as a parameter
• Caching
•
HTTP Provides this!
• 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
•
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)