The Web APIs
Jul 16, 2015
The Web APIs
Ioseb Dzmanashvili !
!
Software Architect at AzRy LLC !
!
!Twitter: https://twitter.com/iosebiGithub: https://github.com/ioseb
What is Web API?
Web API is an umbrella term and means anything that is based on core Web protocols and concepts. Namely
HTTP, URI and Media Types.
What is HTTP?
The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed,
collaborative, hypertext information systems. !
Hypertext Transfer Protocol RFC, HTTPbis
HTTP Has Many Uses/Applications
•Data Transportation
•RPC(Remote Procedure Call)
•Primitive CRUD(Create/Read/Update/Delete)
•Hypermedia Systems
•etc…
What is URI?
A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or
physical resource. !
Uniform Resource Identifier [RFC3986]
An application programming interface (API) specifies how some software components should
interact with each other.
What is an API?
Data Oriented Approach
HTTP/1.1 200 OK Content-Type: application/json Content-Length: … !{ "score": 1337, "playerName": "Sean Plott", "cheatMode": false, "createdAt": "2011-08-20T02:06:57.931Z", "updatedAt": "2011-08-20T02:06:57.931Z", "objectId": "Ed1nuqPvcm" }
Control Oriented ApproachHTTP/1.1 200 OK Content-Type: text/html Cache-Control: private, max-age=0 Content-Length: ... !<!DOCTYPE html> <html> <head> <title>Hello World</title> <link rel="stylesheet" href="style.css" type="text/css"> </head> <body> <section> <header> <img src="/logo.png"> </header> <form method="post" action="/users" enctype="..."> <label> User name: <input type="text" name="user-name"> </label> <button type="submit" name="create">Create</button> </form> </section> </body> </html>
Control Oriented Approach
Some Basics
<many different links>
<a href…> <img src…> <link href…> <video…> <audio…> <form action…>
Method safe idempotent visibility cacheable
GET Yes Yes Yes YesHEAD Yes Yes Yes YesPUT Yes YesDELETE Yes YesPOST(a) PartialPOST(p)
Uniform HTTP Methods
HTTP Response Codes for Dummies
Status Code Range Description
20x Cool.
30x ask that dude over there.
40x you fucked up.
50x we fucked up.
@DanaDanger
Though We Often See….
HTTP/1.1 200 OK Content-Type: application/json Content-Length: … !{"error": "Hey dude you fucked up..."}
7 Lines of Text
http://service.org/simpsons/ijk
Resource Identifier
Request Message
GET /simpsons/ijk HTTP/1.1 Host: service.org
Response MessageHTTP/1.1 200 OK Content-Type: image/jpeg Content-Length: ... !!!!!!!!!!!!
}Representation
}Interpretation
HTTP/1.1 200 OK Content-Type: image/jpeg Content-Length: ... Link: </simpsons/ijk>; rel="self"; title=“Bart" ![BINARY DATA HERE]
The “self” Link Relation Type
The “self” Link Relation Type
Conveys an identifier for the link's context. !
[RFC4287]
Bart
HTTP/1.1 200 OK Content-Type: image/jpeg Content-Length: ... Link: </simpsons/ijk>; rel="self edit"; title=“Bart" ![BINARY DATA HERE]
The “edit” Link Relation Type
The “edit” Link Relation Type
Refers to a resource that can be used to edit the link's context.
![RFC5023]
Bart
Bart Apply
HTTP/1.1 200 OK Content-Type: image/jpeg Content-Length: ... Link: </simpsons/ijk>; rel="self edit"; title="Bart", </simpsons/>; rel="collection"; title="The Simpsons” ![BINARY DATA HERE]
The “collection” Link Relation Type
The “collection” Link Relation Type
The target URI points to a resource which represents the collection resource for the
context URI. !
[RFC6573]
BartSimpsons
HTTP/1.1 200 OK Content-Type: image/jpeg Content-Length: ... Link: </simpsons/ijk>; rel="self edit"; title="Bart", </simpsons/>; rel="collection"; title="The Simpsons", </simpsons/abc>; rel="prev"; type="image/gif"; title=“Homer" ![BINARY DATA HERE]
The “prev” Link Relation Type
The “prev” Link Relation Type
Indicates that the link's context is a part of a series, and that the previous in the
series is the link target. !
[HTML Spec]
Bart
Homer
Simpsons
HTTP/1.1 200 OK Content-Type: image/jpeg Content-Length: ... Link: </simpsons/ijk>; rel="self edit"; title="Bart", </simpsons/>; rel="collection"; title="The Simpsons", </simpsons/abc>; rel="prev"; type="image/gif"; title="Homer", </simpsons/xyz>; rel="next"; type="image/png"; title=“Marge" ![BINARY DATA HERE]
The “next” Link Relation Type
The “next” Link Relation Type
Indicates that the link's context is a part of a series, and that the next in the series is
the link target. !
[HTML Spec]
Bart
Homer Marge
Simpsons
Control Oriented Approach
An affordance is a relationship between the properties of an object and the capabilities of the
agent that determine just how the object could possibly be used.
… Think of each action by the user as an attempt to step in
the right direction; an error is simply an action that is incompletely or improperly specified. Try support, not to fight, the user's responses. Design explorable systems.
!Don Norman
When I say hypertext, I mean the simultaneous presentation of information and controls
such that the information becomes the affordance through which the user (or automaton)
obtains choices and selects actions !
Roy T. Fielding 2008
Questions?