High PerformanceAPIs

Jacksonfdamhttp://about.me/jacksonfdamhttps://bitbucket.org/jacksonfdamhttps://github.com/jacksonfdamhttp://linkedin.com/in/jacksonfdam@jacksonfdam

APIs: Windows To The Code

In the simplest terms, APIs are sets of requirements that govern how one application can talk to another.

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.

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.

API Analogy

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

Webservices

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

Webservices

Most often-used types of web service:

• SOAP• XML-RPC• JSON-RPC• REST

Webservices

Most often-used types of web service:

• SOAP• XML-RPC• JSON-RPC• REST

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.

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.

JSON-RPC

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

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.

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

REST Principles

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

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).

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.

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

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.

Layman terms

What is the difference between REST and SOAP?

Layman terms

What's the difference between MVC and HTTP?

Layman terms

MVC and REST are architectural patterns.

Layman terms

HTTP and SOAP are set of rules i.e. protocols.

Layman terms

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

process.

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.

Layman terms

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

Layman terms

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

Layman terms

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

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.

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.

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.

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. :)

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).

RESTful API

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

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>

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

RESTful APIMultiple 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>

RESTful APIMultiple 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

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

RESTful APIDomain 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

…

RESTful APIDomain 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 …

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 …

RESTful APIDomain 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

RESTful API

Domain Model as Foundation Fine-grained Request

Allows client to construct custom callsBetter 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/tinyusercardAllows optimization on the backend

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

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

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)

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

Thank you!

jacksonfdam@gmail.com tfin

Email Social media

@jacksonfdam

@mafra.jackson

@jacksonfdam