The document discusses APIs and provides examples of RESTful APIs. It describes how RESTful APIs are built upon a domain model to provide resources that can be navigated through requests. This allows clients to construct custom requests to get precisely the data needed, rather than requiring multiple calls or getting excess data. The domain model also provides a unified framework for request and response semantics.

1. High Performance
APIs

2. Jacksonfdam
http://about.me/jacksonfdam
https://bitbucket.org/jacksonfdam
https://github.com/jacksonfdam
http://linkedin.com/in/jacksonfdam
@jacksonfdam

3. APIs: Windows To The Code
In the simplest terms, APIs are sets of requirements that govern
how one application can talk to another.

4. APIs: Windows To The Code
APIs do all this by exposing some of a program's internal
functions to the outside world in a limited fashion.

5. API Analogy
Every time you want to access a set of data from an application,
you have to call the API. But there is only a certain amount of
data the application will let you access, so you have to
communicate to the operator in a very specific language—a
language unique to each application.

6. API Analogy

7. A simple classification of APIs
Web service APIs
- SOAP
- XML-RPC and JSON-RPC
- REST
WebSocket APIs
Library-based APIs
- JavaScript
- TWAIN
Class-based APIs (object orientation)
- Java API
- Android API
OS functions and routines
- Access to file system
- Access to user interface
Object remoting APIs
- CORBA
- .NET
Remoting Hardware APIs
- Video acceleration
- Hard disk drives
- PCI buses

8. Webservices
A description of the communication methods allowed
• Requesting information
• Sending information
• Updating information

9. Webservices
Most often-used types of web service:
• SOAP
• XML-RPC
• JSON-RPC
• REST

10. Webservices
Most often-used types of web service:
• SOAP
• XML-RPC
• JSON-RPC
• REST

11. SOAP (Simple Object Access Protocol)
SOAP is a protocol that defines the communication method,
and the structure of the messages.
The data transfer format is XML.
A SOAP service publishes a definition of its interface in a
machine-readable document, using WSDL – Web Services
Definition Language.

12. XML-RPC
XML-RPC is an older protocol than SOAP. It uses a specific XML
format for data transfer, whereas SOAP allows a proprietary
XML format.
An XML-RPC call tends to be much simpler, and to use less
bandwidth, than a SOAP call. (SOAP is known to be “verbose”.)
SOAP and XML-RPC have different levels of support in various
libraries.

13. JSON-RPC
JSON-RPC is similar to XML-RPC, but uses JSON instead of
XML for data transfer.

14. REST (Representational state transfer)
REST is not a protocol, but rather a set of architectural
principles. The thing that differentiates a REST service from
other web services is its architecture. Some of the
characteristics required of a REST service include simplicity of
interfaces, identification of resources within the request, and
the ability to manipulate the resources via the interface. There
are a number of other, more fundamental architectural
requirements too.

15. REST Principles
It is these principles that characterize most of REST-based APIs
in use today:
• Precedence of the client-server relationship
• Requirement for stateless communication
• Implementation of cache constraints to engender efficiencies in network
communications
• Use of a uniform interface through standardized data elements such as
resources and representations

16. REST Principles
The common perception is that REST offers a lightweight alternative to
service-orientated mechanisms such as SOAP.

17. REST Principles
REST allows for the fine-grained control of objects through the use of
resources (expressed as URIs) that also allows for greater efficiency in
communications with the server (obviously important when implemented on
a mobile device).

18. XML and JSON
The growth of REST has been complemented by the increasing use of
JavaScript Object Notation (JSON) as the mechanism by which resources are
represented.

19. XML and JSON
Mobile apps driving the adoption of web APIs and the need for a compact
payloads over constrained communication links.
The consumption of web APIs by a web developer community and the
resonance of JSON-encoded data with this audience

20. XML and JSON
The use of JSON over XML is not a dichotomy. You will make design
decisions where you support one, both, or even other formats dependent on
the intended audience.

21. Layman terms
What is the difference between REST and SOAP?

22. Layman terms
What's the difference between MVC and HTTP?

23. Layman terms
MVC and REST are architectural patterns.

24. Layman terms
HTTP and SOAP are set of rules i.e. protocols.

25. Layman terms
In layman terms you are asking - What's the difference between a building
plan-map and building making process.

26. Layman terms
Building Plan map is deciding how you will place different things e.g.
Bathroom, dining room, doors, bed-room etc. in a particular geographical
area.

27. Layman terms
MVC is deciding how you will separate concerns regarding data, business
logic and controls.

28. Layman terms
REST is deciding how you will use different HTTP verbs to perform one of
CRUD operation on your data.

29. Layman terms
Building making process is following predefined steps like first create
foundation then walls and in the end go for roof.

30. Layman terms
HTTP is following predefined rules like you need to send request on port 80
which will consist of two parts: HTTP headers and HTTP body.

31. Layman terms
SOAP is following predefined set of rules how and where you can place
function to be called and various parameters to be passed in that function in
your XML SOAP request.

32. Layman terms
SOAP is rigid XML structure. XML is overwhelmed by data-size.
REST can use XML or JSON.
JSON is just key - value pairs.

33. Layman terms
Use SOAP:
1. when you have no other option provided by API exposer.
2. when your end user want to have only SOAP response.
3. Faster development. As tools Axis 2 and cxf exist. :)

34. Layman terms
Use REST(with JSON):
1. To have cleaner software architecture.
2. To save server resources (JSON is smaller to process).
3. To save network resources (JSON size is smaller than XML).
4. To save client side resources (JSON is much faster to parse).

35. RESTful API
http://social.yahooapis.com/v1/user/{guid}/profile
http://api.linkedin.com/v1/people/{guid}

36. RESTful API
<?xml version="1.0" encoding="UTF-8"?>
<person>
<id>111222</id>
<first-name>Jackson</first-name>
<last-name>Mafra</last-name>
<headline>Software Engineer</headline>
<connections total=”1776"> …
</person>

37. RESTful API
What’s Missing?
Ability to get exactly what you need (variety)
• If you need more, may require multiple API calls (if they exist)
• If you need less, resources are wasted
Consistency of responses (uniformity)
• “Same” object returned by different APIs may have different structure
• Once in production, hard to get consistent later

38. RESTful API
Multiple Calls to Get What You Need
Want to get user’s friend’s profile? Do this…
http://social.yahooapis.com/v1/user/123/connections
<connections yahoo:start="0" yahoo:count="1" yahoo:total="1">
<connection yahoo:uri="http://social.yahooapis.com/v1/user/123/connection/456? view=usercard">
<guid>456</guid>
<contactId>4</contactId>
</connection>
</connections>

39. RESTful API
Multiple Calls to Get What You Need
… then make second call to get friend’s profile:
http://social.yahooapis.com/v1/user/456/profile
<profile yahoo:uri="http://social.yahooapis.com/v1/user/456/profile">
<guid>456</guid>
<birthdate>3/3</birthdate>
<created>2008-08-4T17:13:56Z</created>
...
</profile>
- Latent, redundant data
- Optimization requires stickiness

40. RESTful API
Typical Solution
Variety versus Uniformity
- Solution: introduce another call
- Desire for variety of responses undermines uniformity of requests
- Leads to RPC-like REST APIs
- Many APIs + Great Documentation = Lots of Reading + Lack of Automation

41. RESTful API
Domain Model as Foundation
Sample Domain Model
/people : Person[] // collection of Person resources
/id : string // primary key
/name : string
/email : string // unique key
/photo : url
/best-friend : Person
/friends : Person[]
/jobs : Job[] // collection of Job resources
/company : Company
/title : string
/start-date : date
/end-date : date …
/companies : Company[]
/name : string
/ceo : Person
…

42. RESTful API
Domain Model as Foundation
Follow request URL to navigate through your model
To get a person’s profile: http://api.linkedin.com/v2/people/123
<person uri=“urn:linkedin:v2:people/123” key=“123”>
<id>123</id>
<name>Reid Hoffman</name>
<email>reid@linkedin.com</email>
<best-friend uri=“urn:linkedin:v2:people/456”/>
</person>
Conventional URL in request
Default representation in response
/people[/id=123]
/id
/name
/email
/photo
/best-friend
/friends
…
/jobs
/company
/title
/start-date
/end-date
…
/companies
/name
/ceo
…

43. RESTful API
Domain Model as Foundation
Fine-grained Request
What if you only need certain fields (e.g., name and photo)?
http://api.linkedin.com/v2/people/123:(name,photo)
<person>
<name>Reid Hoffman</name>
<photo>http://media.linkedin.com/photos/123.jpeg</photo>
</person> …
/people[/id=123]
/id
/name
/email
/photo
/best-friend
/friends
/jobs
/company
/title
/start-date
/end-date
…

44. RESTful API
Domain Model as Foundation
Fine-grained Request
To get names and photos of one’s friends and their best friends:
…/v2/people/456/friends:(name,photo,best-friend: (name,photo))
<friends total=“66” start=“0”>
<friend uri=“urn:linkedin:v2:people/123” key=“123”>
<name>Reid Hoffman</name>
<photo>http://media.linkedin.com/photos/123.jpeg</photo>
<best-friend uri=“urn:linkedin:v2:people/456” key=“456”>
<name>Brandon Duncan</name>
<photo>http://media.linkedin.com/photos/456.jpeg</photo>
</best-friend>
</friend>
<friend>…</friend>
</friends>
…
/people[/id=456]
/id
/name
/email
/photo
/best-friend
/friends
/123
/id
/name
/email
/photo
/best-friend
/name
/photo
/jobs

45. RESTful API
Domain Model as Foundation
Fine-grained Request
Allows client to construct custom calls
Better than digging for the closest matching API:
http://social...com/v1/user/123/profile
http://social...com/v1/user/123/profile/usercard
http://social...com/v1/user/123/profile/tinyusercard
Allows optimization on the backend

46. RESTful API
Domain Model as Foundation
Fine-grained Request
Benefits
- Provides a frame for both request and response semantics
- Still allows for flexible syntax
- Requests – path, query params, matrix params…
- Responses – JSON, XML…
- Helps to unify and automate many development tasks on both ends
- Request / response creation, parsing, marshalling
- Code (and documentation) generation
- Discovery services

47. RESTful API
Domain Model as Foundation
Fine-grained Request
Benefits
- Provides a frame for both request and response semantics
- Still allows for flexible syntax
- Requests – path, query params, matrix params…
- Responses – JSON, XML…
- Helps to unify and automate many development tasks on both ends
- Request / response creation, parsing, marshalling
- Code (and documentation) generation
- Discovery services

48. RESTful API
Examples of LinkedIn APIs HTTP GET - Read
…/people/email=brandon@gmail.com/friends?sort=name
…/people/123/friends;sort=name:(name,jobs;sort=start-date)
…/people:(id,name,photo)?name=page&company=google
…/people::(123,456)
…/people::(123,456):(name,photo)

49. RESTful API
Incentive System
• Multiple ways to get at the same data
• Partner can ask for exactly what they need
• Associate cost with resources, system of accounting creates incentives for
partners
• Throttling by resource rather than API

50. Thank you!
jacksonfdam@gmail.com
t
f
in
Email Socialmedia
@jacksonfdam
@mafra.jackson
@jacksonfdam