Upload
integratorbrad
View
2.368
Download
141
Embed Size (px)
DESCRIPTION
Presentation on introducing Web APIs to Communitech P2P Web Developers group on Feb 20, 2014
Citation preview
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
API Example
vs
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?
• 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
Verbs, Level 2 REST
• CRUD
What is CRUD?
• Standard database operations:C reateR eadU pdateD 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 PUT POST DELETE
Collection URI(such as http://a.com/items/)
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
Element URI(such as http://a.com/items/17)
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-apishotnotgluecon2012
Important : Know your TTFHW (Time to First Hello World) !
API Worst Practices
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
Source: http://www.slideshare.net/jmusser/j-musser-apishotnotgluecon2012
The Security
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 Session Management
Authentication 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
• Use an AJAX Call$.ajax({type : "GET",url : "http://a.com/tweets",data : {"contains" : "API"},dataType : "json",success : function(data){ alert ("Results: " + data);}
});
Verb
Query parameters
Resource
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
The Examples
Some REST API Examples
• If This, Than That
• Twilio
• Demo
Facebook Graph API• Every object has an ID:
• Objects can be searched:
• Objects can be updated:
Twitter REST API
If This, Then That
• API Integration Website - http://ifttt.com/
Twilio
Demo
Need more REST?
• Programmable Webhttp://programmableweb.comJohn 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
Discussion - Questions