Bp209

BP209 In The Land Of Social Apps
The API Is King
Mikkel Flindt Heisterberg | Senior Solution Architect, Intravision
Ryan Baxter | Software Engineer, IBM

© 2013 IBM Corporation

Please note

IBM’s statements regarding its plans, directions, and intent are subject to change or withdrawal
without notice at IBM’s sole discretion.
Information regarding potential future products is intended to outline our general product direction
and it should not be relied on in making a purchasing decision.
The information mentioned regarding potential future products is not a commitment, promise, or
legal obligation to deliver any material, code or functionality. Information about potential future
products may not be incorporated into any contract. The development, release, and timing of any
future features or functionality described for our products remains at our sole discretion.

Performance is based on measurements and projections using standard IBM benchmarks in a
controlled environment. The actual throughput or performance that any user will experience will
vary depending upon many factors, including considerations such as the amount of
multiprogramming in the user's job stream, the I/O configuration, the storage configuration, and the
workload processed. Therefore, no assurance can be given that an individual user will achieve
results similar to those stated here.

2 © 2013 IBM Corporation

About us
 Mikkel Flindt Heisterberg - @lekkim
─ With IntraVision, makers of the OnTime Group Calendar – we're in
the showcase
─ IBM Champion
─ Design Partner for Notes and IBM Connections
─ Enjoys coming to the US (Sam Adams, diet root beer, chocolate
glazed donuts...)


 Ryan Baxter - @ryanjbaxter
─ Software Engineer, IBM
─ Developer for IBM Notes
─ Lead developer for Notes Client Java UI APIs
─ OpenSocial Foundation Member and Apache Shindig committer
─ Enjoys building apps!
─
─


Credit

 IBM® Notes® Social Edition
 IBM® Domino® Social Edition
 IBM® iNotes® Social Edtion
 IBM® Connections®
 IBM® Social Business Toolkit
 IBM® WebSphere® Application Server (WAS)


API == Application Programming Interface


Agenda

 What's an API to you?
 Why Build APIs?
 Good APIs vs. Bad APIs
 Internal vs. External
 API Versioning
 Authentication and Authorization
 Lessons Learned From Building APIs
 Developer Resources
 Q&A
─


What's an API to you?

 “API” can mean different things to different people
 In this presentation when we talk about APIs they can be a
─ Data API
An API with the purpose of making it easier to interact with some thing e.g. the IBM Social
Business Toolkit making it easier to interact with the activity stream.
─ Wrapper API
A wrapper API (or “facade”) is for making a low level API easier to use and easier to grasp.
Examples could be the IBM Social Business Toolkit JavaScript API (wraps, among other things,
the IBM Connections REST API) or Dojo that, among other things, makes the DOM easier to
work with and reduces boilerplate JavaScript.
─ UI API
A special case of wrapper API to help you build UI's by providing a UI abstraction.


 Most APIs will actually consists of more than one part – when you define an API
it will probably have a “data piece” and a “wrapper piece” i.e. a piece on the
server and a piece to make it easier to use the data API from, say, a JavaScript
library.


Why Build APIs?

 The number one reason to build APIs is to provide a service to your users
─ Users may be customers, partners, or even other developers on your team
─ The goal should be to enable use cases that would be impossible or difficult to achieve without
the API
 APIs are all about value
─ What is valuable to your users?
– Your data
– A service you provide
– A mashup
– Your users / customers
 Define metrics to measure the success of your API
─ How does it help the business, your partners, your customers?
 Tighter integration into the applications your users are using today
─ Sidebar apps in Connections, Notes, iNotes
─ Embedded Experiences, Widgets, Dashboards, etc.


Most Used APIs (2012)

Mapping
Social
Search
Photos
Shopping
Video
Music
Telephony
Internet
Messaging

Source: Programmable Web 2012


Social API Growth

500

450

400

350

300

250

200

150

100

50

0
2005 2006 2007 2008 2009 2010 2011 2012

Source: Programmable Web


Designing Good APIs

 Planning is the key to the success of any API
─ Define the use cases for the API. What are you going to enable?
─ If you don't plan your end up with a confusing, unusable API set which provides NO value to
anyone
─
 What protocol(s) are you going to use?
─ REST, SOAP, JavaScript, ATOM, etc
─
 What data model(s) are you going to use?
─ JSON, XML, CSV, Text, etc
─
 Don't try and support everything! Start with what what makes sense for your
consumers


 Be consistent and intuitive with your APIs
─


Which API would you prefer to call?

SOAP REST
POST /InStock HTTP/1.1 GET /rest/stockprice/ibm HTTP/1.1
Host: www.example.org Host: www.example.com
Content-Type: application/soap+xml; charset=utf-8
Content-Length: nnn

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-
encoding">
<soap:Body xmlns:m="http://www.example.org/stock">
<m:GetStockPrice>
<m:StockName>IBM</m:StockName>
</m:GetStockPrice>
</soap:Body>
</soap:Envelope>


XML or JSON which one do I choose?

XML JSON
<person {
xmlns="http://ns.opensocial.org/2008/opensocial"> "id" : "1234",
<id>1234</id> "displayName" : "Janey",
"name" : {"formatted" : "Jane Doe"}
<displayName>Janey</displayName> }
<name>
<formatted>Jane Doe</formatted>
</name>
</person>


Language Support


“My users are not developers!”

 You don't need to be providing a service
to everyone in order to have an API....
the term “users” is vague intentionally :)


 Your users may be other developers on
your team don't you think they like APIs
too?


 Components within an app may have
APIs which allow them to evolve
independently of other internal consumers


 If you decide to open the API up to a wider audience later on you don't have
to do a bunch of work



Supporting Your API

 What good is an API if you can't figure
out how to use it?
 TTFHW
─ “Time to first hello world”
─ If it takes to long to get to hello world your API is going to fail
 Samples, Samples, Samples!
─ Code samples are a must, developers don't read documentation they write code!
─ Make them simple and strait forward so developers can easily understand what is happening
 Tooling
─ Debuggers, playgrounds, explorers, dashboards, etc
─ With tooling the TTFHW decreases drastically
 Community
─ Engage the community of developers using your APIs
─ You cannot scale to support the API but the community does scale
─ Gives new comers the impression that the API is useful and that they can find help when they
need it


Google's OAuth 2 Playground & API Explorer


HTML 5 Playground


IBM Social Business Toolkit Playground

http://bit.ly/sbtplayground

Playtime

 Demo SBT Playgroup
 Maybe demo OnTime API Explorer


API Versioning

Some of the changes that will occur are
Your API
●

● Input requirements changing (new requirements, new
meaning) will
Input format changing (plain text to JSON, supporting
change...
●

multiple input formats)
● Output format changing (plain text to JSON, new structure) Even though
● Once an API is public and consumed you have to
handle change you say it
● The key is designing for change – if you're wont – it
● providing a JavaScript library allow the caller to specify the
version he/she depends on in the URL (
will!
http://www.example.com/app.nsf/v1.7.2/library.js) to avoid
your updates breaking applications their application
● providing a data API allow the caller to use a versioned
endpoint or allow the caller to specify the version they rely on
“out of band” e.g. in a HTTP header


API Versioning for non-public APIs

Yeah – it's all good with all
that talk of change
management but my API is not
public – it's only me using it! Well okay – but you probably
have more than one client / app
and will they all be updated
simultaneously? Probably not.

Fine... But I only have the one
app and it's never going to
Well in 6 months you'll need
change!
another app that use the same
API but the data format
requirements are different. So
it's just good sense to design
for change.


Security as it pertains to APIs

 Deciding how to handle security is a key design point


 Ask yourself questions like “is authentication always feasible?” or “should there
be some alternative way of authentication?”
─ Relying on username / password is the easy choice but has its limitations as clients using your
API may need to store it (on someone's behalf)
─ How about (mobile) web apps – is it okay to have the user (re)authenticate? Do you need to
support persistent authentication?
─ Do you need to be able to grant access without the user authenticating (i.e. a user being auto-
authentication)
 Decide on how to signal authentication and authorization errors up front
─ For HTTP based API's you can use HTTP response codes or always
return HTTP code 200 with a response message indicating success or failure
─ Other transports may need other mechanisms





Authentication and authorization

 Securing the access to a resource or an API endpoint is made up of two parts
1) Making sure the user/process/program is who he/she/it says it is (proving identity) – we call this
authentication
2) Making sure the user/process/program is allowed to work with, make calls against or operate on
the data (proving access right) – we call this authorization
● Authentication can be done using a variety of mechanisms
● Username / password
● Certificates
●
3rd party trust e.g. SAML
● Ideally authentication should be external to the API and
multiple approaches supported
● Authorization may either be declarative in the application
container (external to application code) or be handled by
the API (done in code)
● Declarative examples – Domino ACL's or Java EE role mapping
●

●


Security in HTTP based API's

 The HTTP protocol has ways of indicating problems with authentication and
authorization as response codes
─ 200 OK
The request has succeeded. The information returned with the response is dependent on the
method used in the request.
─ 401 Unauthorized
The client MAY repeat the request with a suitable Authorization header field. If the request
already included Authorization credentials, then the 401 response indicates that authorization
has been refused for those credentials.
─ 403 Forbidden
The server understood the request, but is refusing to fulfill it Please note: This
is an
─ 404 Not Found
The server has not found anything matching the Request-URI. No interpretation of
indication is given of whether the condition is temporary or permanent. the HTTP response
codes – feel free to
 If using Domino agents you're stuck with HTTP code 200 reject it...
as the HTTP task handles the authentication and
authorization before it reaches the agent


─


Example of HTTP code 200 for success and error

{
APIBuild: 423,
Status: “Error”,
StatusNum: 24,
StatusText: “Bummer! Not authorized”
}

{
APIBuild: 423,
Status: “OK”,
StatusNum: 0,
UsersInfo: {
Status: “OK”,
“StatusNum”: 0,
...
}
}

Example of allowing auto and persistent authentication


Authorization using OAuth

 The standard used for Authorization is called OAuth
─ OAuth stands for open authorization NOT open authentication
─ Applications access users data via APIs on the behalf of the user NOT as the user
─ The most recent version of the OAuth is 2.0 although 1.0a is still widely used
─
 In terms of OAuth your application or APIs will be protected by an OAuth
provider
─ Developers using your API will go to the OAuth privider to register their application and receive
an OAuth key and secret
─ The application using your APIs acts as the OAuth client
─
 There are plenty of open source OAuth implementations available to use
─ Clients
– XPages Social Enabler, IBM Social Business Toolkit, Notes, iNotes, Connections

─ Providers
– IBM working on / investigating OAuth provider for Domino
– OAuth provider on WAS 8


OAuth Flow
API Request

Request
Browser Access

Developer Do you want to allow Acme App access
App to your data? Approval
(OAuth client) YES NO

Learning
resource: “OAuth
for Domino
API Response Developers” by
Julian Robichaux


Lessons learned from building APIs

 We started with a NRPC based API only
─ Lesson learned: From the get-go be prepared to support multiple endpoint types – now we also
support HTTP
 We accepted only plain text input
─ Lesson learned: Now we're allowing the API user to both supply in the input in plain text
(backwards compatibility) and in JSON as it's easier for web clients.
 We returned data in a proprietary array based format that resembled the
representation on the server
─ Lesson learned: Too difficult to use and parse for clients and customers. We're now moving to be
entirely JSON based to make the response easier to parse but we're keeping the old format for
backwards compatibility
 We will only need to use our API from our own client UIs
─ Lesson learned: Not so much. Once we had the API the sky becamethe limit and we're
constantly coming up with new use cases and new ways to use the API. Being able to use the
API over NRPC and HTTP was key. NRPC can also be own clients (plugins) but also agents,
XPages and web services



“Get my calendar data for this “Login to figure out who “I” am” Package command and talk to
week sorted ascending by date” “Get my user id” server endpoint
“Get calendar data for this week”
“Sort appointments ascending by
date”

HTTP

Delegates communication to transport
transport

High level
Low level Notes
Uses

API
API transport
(“facade”)

Notes
transport
(w/ session)

Client application / request Client application / request



 Be prepared for failure, you won't get it
right the first time!
─ Rewriting an API and implementation multiple
times is common
─
 Make your API flexible
─ You will never be able to predict all the use cases
for your API
─ If you make your API flexible you will be able to
adapt to new use cases as they come along
─
 Make it easy for people to build apps using
your API
─ If it is complicated to deploy people won't use it
– I.E WAS + Connections + Domino +
Sametime + Notes + iNotes
─
─


Resources

 OAuth
http://www.oauth.net
 “OAuth for the Domino Developer”Julian Robichaux
http://www.slideshare.net/dominopoint/dd12-oauth-for-domino-developers
 IBM Social Business Toolkit
http://www.ibm.com/developerworks/social/
 Google Code Playground
http://code.google.com/apis/ajax/playground/


 Our blogs :)
─ Ryan: http://ryanjbaxter.com/
─ Mikkel: http://lekkimworld.com
─


That's it! Hope you found it useful...


Legal disclaimer
© IBM Corporation 2013. All Rights Reserved.
The information contained in this publication is provided for informational purposes only. While efforts were made to verify the completeness and accuracy of
the information contained in this publication, it is provided AS IS without warranty of any kind, express or implied. In addition, this information is based on
IBM’s current product plans and strategy, which are subject to change by IBM without notice. IBM shall not be responsible for any damages arising out of the
use of, or otherwise related to, this publication or any other materials. Nothing contained in this publication is intended to, nor shall have the effect of,
creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement
governing the use of IBM software.
References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product
release dates and/or capabilities referenced in this presentation may change at any time at IBM’s sole discretion based on market opportunities or other
factors, and are not intended to be a commitment to future product or feature availability in any way. Nothing contained in these materials is intended to, nor
shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results.


Bp209

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Bp209

Similar to Bp209 (20)

Bp209