Vector Search -An Introduction in Oracle Database 23ai.pptx
Introduction to the Web API
1. An Introduction into
the Web API
Brad Genereaux | @integratorbrad | about.me/integratorbrad | hcintegrations.ca
Web Developers P2P : February 2014
2. 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
11. What is REST?
• Architectural style (not a standard!)
• Client server model
• Stateless
– Idempotency
• Cacheable
• Layered System
• Uniform interface
15. What do I need to REST?
Clients
• Browsers
• Mobile Apps
• Desktop Apps
Servers
• “Capable of HTTP”
–
–
–
–
–
–
Java-based
.Net-based
PHP
Ruby
Perl
Etc.
16. Three levels of REST
• Level 1 : Resources
• Level 2 : Verbs
• Level 3 : HATEOAS
19. What is CRUD?
• Standard database operations:
C reate
R ead
U pdate
D elete
20. 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)
21. 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
23. 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
24. 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
25. REST Alternatives
• SOAP (simple object access protocol)
• Javascript
• XML-RPC
• See discussion at
http://www.slideshare.net/jmusser/j-musser-ap
27. 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
32. 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/
34. 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;
}
35. 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
36. 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
37. 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
38. 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
39. 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
40. Other Frameworks
•
•
•
•
UI Frameworks (Bootstrap, Foundation)
MVC Frameworks (Angular, Backbone)
Tooling (Yeoman, Lineman)
Documentation (Apiary, Swagger)
• No shortage of options
48. 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
Describes a method for a client to communicate with a server
If you ever access a website, you are already using REST
When you access a page, you are GETting it.
Easy to consume by many platforms
Lightweight, payload is almost strictly content
Self-documenting
Flexible for many environments, including firewalls and load-balancers
Just “works” for security and identity frameworks
Server and consumer agnostic
Both represent the same data, albeit in different ways
JSON is smaller, but with compression, they are ~equivalent
XML can be validated (XML Schema), stylized (XSL), traversed (XPath), queried (XQuery), transformed (XSLT), and namespaced
JSON has no formally recognized equivalents, which isn’t necessarily a bad thing
I can reasonably guess functionality without needing documentation
TTFHW – Time to first hello world