Introduction to the Web API

An Introduction into
the Web API

Brad Genereaux | @integratorbrad | about.me/integratorbrad | hcintegrations.ca
Web Developers P2P : February 2014

Housekeeping
• About Me - Brad Genereaux
– Healthcare and API developer
– Integration Architect at Agfa Healthcare
– Blogger about all the API things

• Discussion and questions
– Ask anytime, or at the end

Topics
•
•
•
•
•

API
REST
Security
Web
Examples

The API

Application Programming Interface

What is an API?
• Methods to access data and workflow
from an application without using the
application itself

Why an API?
• Not all users are the same
– Some want:

– Some want / need:

– And their needs and wants are ever shifting

An API Stack
GUI
(front-end)

API
(middle tier)

Data Sources
(back-end)

… sounds like a good framework
for Web …

The REST

REpresentational State Transfer

What is REST?
• Architectural style (not a standard!)
• Client server model
• Stateless
– Idempotency

• Cacheable
• Layered System
• Uniform interface

Source: https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf

Who RESTs?
•
•
•
•
•
•
•

Facebook
Twitter
Google
LinkedIn
Netflix
Evernote
Etc etc

Why REST?
•
•
•
•
•

Scalable
Fault-tolerant
Recoverable
Secure
Loosely coupled

What do I need to REST?
Clients
• Browsers
• Mobile Apps
• Desktop Apps

Servers
• “Capable of HTTP”
–
–
–
–
–
–

Java-based
.Net-based
PHP
Ruby
Perl
Etc.

Three levels of REST
• Level 1 : Resources
• Level 2 : Verbs
• Level 3 : HATEOAS

Resources, Level 1 REST
•
•
•
•

/users
/users/bob
/users/bob/tweets
/users/bob/tweets/1

What is CRUD?
• Standard database operations:
C reate
R ead
U pdate
D elete

Verbs, Level 2 REST
• CRUD
• GET /tweets
(as opposed to /givemethetweets)

• POST /tweets
(as opposed to /createnewtweet)

• PUT /tweets/1
(as opposed to /updatetweet/1)

• DELETE /tweets/1
(as opposed to /removetweet/1)

RESTful Methods
GET
Collection URI
(such as
http://a.com/items/)

Element URI
(such as
http://a.com/items/17)

PUT

POST

DELETE

List the items in
the collection and
some metadata
about the items

Replace the entire
collection with
another collection

Create a new entry in
the collection, and
return the reference

Delete all the
items in the
collection

Retrieve a
specific item in
the collection

Replace a specific
item in the
collection; if it
doesn't
exist, create it

Not generally used

Delete the
specific item
in the
collection

• There are other methods less used (HEAD, OPTIONS, PATCH) for other purposes
• Representations of an item are specified by the media type (MIME type)

Source: http://en.wikipedia.org/wiki/Representational_state_transfer

HATEOAS, Level 3 REST
• Hypermedia as the engine of
application state

"ids" : [
12345678,
87654321,
11223344
]

"links": [
{
"rel": "UserInfo",
"href": "https://.../user/12345678"
},
{
"rel": "Tweets",
"href": "https://.../tweet/87654321"
},
{
"rel": "Messages",
"href": "https://.../msgs/11223344"
}
]

Data Formats (XML and JSON)
 XML (135 characters):
<tweets>
<tweet type="text" id="1">
<text>REST is great!</text>
</tweet>
<tweet type="text" id="2">
<text>APIs forever!</text>
</tweet>
</tweets>

 JSON (109 characters):
{
"tweets": [
{"type": "text", "id": "1",
"text": "REST is great!"},
{"type": "text", "id": "2",
"text": "APIs forever!"}
]
}

 XML can be validated (XML Schema), stylized (XSL), traversed

(XPath), queried (XQuery), transformed (XSLT), and
namespaced
 JSON is easier

What makes for good REST?
• Self-documenting
• Nouns in path, verbs by HTTP
• Complexity under the “?”
– i.e., /tweets/?contains=API

• Errors use HTTP error code mechanism
• As simple as possible, but no simpler

REST Alternatives
• SOAP (simple object access protocol)
• Javascript
• XML-RPC

• See discussion at
http://www.slideshare.net/jmusser/j-musser-ap

Important : Know your TTFHW
(Time to First Hello World) !

API Worst Practices
Source: http://www.slideshare.net/jmusser/j-musser-apishotnotgluecon2012

10. Poor error handling
9. Ignoring HTTP rules
8. Exposing your underlying data model
7. Security complexity
6. Unexpected release cycles
5. Poor developer experience
4. Expecting an MVC to give you a great API
3. Assuming if you build it, they will come
2. Inadequate support
1. Poor documentation

Authentication and Authorization
• Authentication : Who
• Authorization : What they are allowed to
do
• Not your job, but your responsibility

Security Frameworks
• OAuth
– Authorizing services

• OpenID
– Facebook, Google

• LDAP
– Enterprise authentication

Application Security Threats
Input Validation
Authentication

Session Management
Cryptography

Authorization

Exception Management

Configuration
Management

Parameter Manipulation

Sensitive Information

Auditing and Logging

Source: http://en.wikipedia.org/wiki/Application_security

SQL Injection

Consider the following pseudo-code:
String topic = request.getParameter(“topic");
SQLCommand sql = new SQLCommand("select * from
tweets where topic like ‘" + topic + "%’")

So what happens if the parameter is:
– API
– REST
– h3ck0rz’; drop table tweets; -Source: http://xkcd.com/327/

The Web

Client-side Access to REST

HTML5 + CSS
• “HyperText Markup Language”
– Characterized by the DOM (document object model) Completely
ubiquitous across the Internet
<html>
<body>
<h1>Hello World</h1>
</body>
</html>

• “Cascading Style Sheets”
– Allows for advanced stylization of content
– Example:

.giant {
font-size: 72px;
color: blue;
}

JavaScript
•
•
•
•

Multi-paradigm weakly-typed scripting language
Used most often hand-in-hand with HTML
Not Java, at all (syntax based on C)
Example:
alert (“Hello World!”);

• Able to manipulate the DOM and interact with the
browser environment

AJAX
• “Asynchronous JavaScript and XML”
• Group of technologies that allow for robust client
interactions without reloading web pages
– HTML and CSS for presentation
– DOM for display and interaction of data
– XML for data interchange
– XMLHttpRequest for asynchronous communication
– JavaScript to bring these technologies together
• AJAX is the key to consuming REST

jQuery
• “jQuery is a fast and concise JavaScript Library that
simplifies HTML document traversing, event handling,
animating, and Ajax interactions for rapid web
development.”
• Example:
$(“#h1”).html(“Hello World!”);

• jQuery tests against many browser platforms and solves
a lot of the problems that supporting many platforms
introduces

Calling REST with jQuery
Verb

• Use an AJAX Call
Resource
$.ajax({
type : "GET",
url : "http://a.com/tweets",
data : {"contains" : "API"},
dataType : "json",
success : function(data){
alert ("Results: " + data);
}
});

Query
parameters
Media type

Tips
• Use “curl” to simulate calls from your
command line
• Use Chrome debug tools or Firebug to
watch traffic and test your Javascript
• Use libraries – no need to reinvent the
wheel

Other Frameworks
•
•
•
•

UI Frameworks (Bootstrap, Foundation)
MVC Frameworks (Angular, Backbone)
Tooling (Yeoman, Lineman)
Documentation (Apiary, Swagger)

• No shortage of options

Some REST API Examples
•
•
•
•
•

Facebook
Twitter
If This, Than That
Twilio
Demo

Facebook Graph API
• Every object has an ID:

• Objects can be searched:

• Objects can be updated:

If This, Then That

•

API Integration Website - http://ifttt.com/

Need more REST?
• Programmable Web
http://programmableweb.com
John Musser’s presentations: http://www.slideshare.net/jmusser

• Crafting Interfaces that Developers Love
http://offers.apigee.com/api-design-ebook-rr/

• API Craft Google Group https://
groups.google.com/forum/#!forum/api-craft

Introduction to the Web API

More Related Content

What's hot

Viewers also liked

Similar to Introduction to the Web API

Recently uploaded

Introduction to the Web API

Editor's Notes