Bp209

BP209 In The Land Of Social Apps The API Is King

Mikkel Flindt Heisterberg | Senior Solution Architect, IntravisionRyan Baxter | Software Engineer, IBM

Please note

IBMs statements regarding its plans, directions, and intent are subject to change or withdrawal without notice at IBMs 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.

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 - @ryanjbaxterSoftware 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 usersUsers 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 valueWhat is valuable to your users?Your data

A service you provide

A mashup

Your users / customers

Define metrics to measure the success of your APIHow does it help the business, your partners, your customers?

Tighter integration into the applications your users are using todaySidebar apps in Connections, Notes, iNotes

Embedded Experiences, Widgets, Dashboards, etc.

Most Used APIs (2012)

Source: Programmable Web 2012

Social API Growth

Source: Programmable Web

Designing Good APIs

Planning is the key to the success of any APIDefine 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?

SOAPPOST /InStock HTTP/1.1
Host: www.example.org
Content-Type: application/soap+xml; charset=utf-8
Content-Length: nnn

IBM

RESTGET /rest/stockprice/ibm HTTP/1.1Host: www.example.com

XML or JSON which one do I choose?

XML

1234 Janey Jane Doe

JSON{ "id" : "1234", "displayName" : "Janey", "name" : {"formatted" : "Jane Doe"}}

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?TTFHWTime 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

ToolingDebuggers, playgrounds, explorers, dashboards, etc

With tooling the TTFHW decreases drastically

CommunityEngage 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 areInput requirements changing (new requirements, new meaning)

Input format changing (plain text to JSON, supporting multiple input formats)

Output format changing (plain text to JSON, new structure)

Once an API is public and consumed you have to handle change

The key is designing for change if you're providing a JavaScript library allow the caller to specify the version he/she depends on in the URL (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

Your API will change... Even though you say it wont it will!

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 change!

Well in 6 months you'll need 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 frontFor 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

Making sure the user/process/program is who he/she/it says it is (proving identity) we call this authentication

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 mechanismsUsername / 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 codes200 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

404 Not Found
The server has not found anything matching the Request-URI. No
indication is given of whether the condition is temporary or permanent.

If using Domino agents you're stuck with HTTP code 200
as the HTTP task handles the authentication and
authorization before it reaches the agent

Please note: This is an interpretation of the HTTP response codes feel free to reject it...

Example of HTTP code 200 for success and error

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

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

Example of allowing auto and persistent authentication

Authorization using OAuth

The standard used for Authorization is called OAuthOAuth 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 providerDevelopers 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 useClientsXPages Social Enabler, IBM Social Business Toolkit, Notes, iNotes, Connections

ProvidersIBM working on / investigating OAuth provider for Domino

OAuth provider on WAS 8

OAuth Flow

Developer App(OAuth client)

API Request

Approval

Do you want to allow Acme App access to your data?YES NOBrowser

Request Access

API Response

Learning resource: OAuth for Domino Developers by Julian Robichaux

Lessons learned from building APIs

We started with a NRPC based API onlyLesson learned: From the get-go be prepared to support multiple endpoint types now we also support HTTP

We accepted only plain text inputLesson 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 serverLesson 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 UIsLesson 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


High level API (facade)Low level APIHTTP transportNotes transportNotes transport (w/ session)

Delegates communication to transport

Uses

Login to figure out who I amGet my user idGet calendar data for this weekSort appointments ascending by dateGet my calendar data for this week sorted ascending by datePackage command and talk to server endpointClient 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 flexibleYou 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 APIIf it is complicated to deploy people won't use itI.E WAS + Connections + Domino + Sametime + Notes + iNotes

Resources

OAuth
http://www.oauth.net

OAuth for the Domino DeveloperJulian 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 IBMs 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 IBMs 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.

Click to edit the outline text format

2013 IBM Corporation

Click to edit the outline text formatSecond Outline LevelThird Outline LevelFourth Outline LevelFifth Outline LevelSixth Outline Level


Click to edit the outline text formatSecond Outline LevelThird Outline LevelFourth Outline LevelFifth Outline LevelSixth Outline Level


Column 1

Mapping3262

Social1504

Search1130

Photos898

Shopping838

Video831

Music502

Telephony447

Internet441

Messaging342

Column 1

20054

20068

200724

200862

2009101

2010202

2011299

2012443

Documents

Bp209