Recommended Practices for Designing a Web API

© 2013 IBM Corporation

Recommended Practices for Designing a Web API

Alan Moore, Senior Technical Staff Member, AIM, SWG

Dinesh Shetty,

Senior Certified IT Specialist, ISSW

2372

22 © 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.


Agenda

•Key Concepts

•API Exposures – Public? Private? Partner?

•Design considerations for a REST-based Web API‒ Walk through of an example application

•Designing a mobile-friendly Web API

•Implementing Caching for your API

•API Security

•Managing and advertizing your API


Key Concepts – Terminologies, technologies & benefits

•Web API‒ A defined set of HTTP request

and response message

‒ typically expressed

in JSON or XML

•Mashup‒ A web application that uses

Web APIs to combine data,

presentation

‒ from two or more sources to

create new services

•Apps‒ An application accessed over

the Internet or an intranet.

‒ Coded in a browser-supported programming language (such

as JavaScript and markup language like HTML)

•Technologies for APIs‒ REST Architectural style

‒ JSON, XML

‒ OAuth

‒ Basic Auth

•Benefits of APIs‒ Quicker, easier and more re-

usable technical access to your

enterprise assets

‒ Rapidly develop web, mobile

and tablet applications from

your organizations technical

assets


Key Concepts – Essentials for successful API

•Follows REST best practices‒ Learning from the popular APIs

‒ Facebook, Twitter, Google etc

•Good meaningful and to-the-point reference documentation

•Simple and important code samples

•Author’s articles

•Managed and open forum‒ Encourage discussion

‒ Answer questions from API users

•Automatic and easy sign-up or registration process‒ Self service

•Clear terms and conditions to follow

•Comprehensive Entitlements & Pricing information


70% of Web APIs are REST; REST is simple

Source: http://www.slideshare.net/jmusser/pw-glue-conmay2010

REST is an architectural style; not a standard


API Exposures – Public? Private? Protected?

7


A Little More Info on the Types Of API Exposures

Public, Open-

To-All APIs

Protected, Open-

To-Partner APIs

Private, Open-

To-Employee

APIs

• APIs are open to any developer who wants to sign up

• Apps are more targeted towards end consumers

• The business driver is to engage customers through external developers

• APIs are open to select business partners

• Apps could be targeted at end consumers or business users

• The business driver is usually different, based on the data and type of business of the enterprise

• APIs are exposed only to existing developers within the enterprise

• Apps are usually targeted at employees of the enterprise

• The business driver is more around productivity of employees


Questions and Considerations

•No “One rule fits all” recommendation – more of a business decision for an organization

•Exposing a Public API‒ You don’t want to expose all the capabilities of your system!

‒ Information Security – what data is shared?

•ESBs, API Management solutions allow you to filter data – expose only required fields from a response

•How much functionality is to be provided in an API?‒ Organizations chose to provide limited, but important capability through

APIs

‒ E.g. Comprehensive banking capabilities Vs. basic quick-use tasks

•Both versions – Public and Private?‒ Management overheads


•Designing a REST-based Web API

• Typical API developer requirements

•Walkthrough

• Sample Application10


Typical API developer requirements

•Value to the application‒ they will put up with a lot if there is high value to the application

•Stability, stability, stability!‒ API has to be up and responsive, otherwise consumers blame the app and

won’t use it (they don’t care about the APIs that are used)

‒ Don’t break my app – Changes need to be additive, backwardly compatible

‒ Don’t change your OAuth logon - breaks the visibility in others apps

•Listen to their feedback‒ Facebook and Twitter APIs have vastly improved from their original APIs

‒ Quick sign up – don’t make me fill out a lot of forms and go back and forth

‒ Allow free trial usage - Let me try it and even better use it for free until I have a

volume of customers

‒ Provide clear documentation - follow standards, provide clear doc, examples,

SDK

‒ Make it easy for me to get help day or night (as I may be in a different

timezone) – with forums, bug reporting, community tools, API status visibility etc

•Show me my API usage, my users’ usage, my data


Use Caching

Architect your backend for scaling

Leverage Asynchronous Messaging

Use Compression

Build on an Elastic Platform


Accounts Contacts

Opportunities

Sample Application

•Define collections‒ Accounts

‒ Contacts

‒ Opportunities

•Define Verbs‒ GET (Equivalent to SQL SELECT)

‒ POST (Equivalent to SQL CREATE)

‒ PUT (Equivalent to SQL UPDATE)

‒ DELETE (Same connotation in SQL)


Account REST API for Sample Application

•GET /Accounts‒ SELECT *

FROM Accounts

•GET /Accounts/{Id}‒ SELECT *

FROM Accounts WHERE Id = ?

•GET /Accounts/{id}/Contacts‒ SELECT C.*

FROM Contacts C

WHERE C.AccountId = ?

•GET /Accounts/{id}/Opportunities‒ SELECT O.*

FROM Opportunities O

WHERE O.AccountId = ?


Contacts REST API for Sample Application

•GET /Contacts‒ SELECT *

FROM Contacts

•GET /Contacts/{Id}‒ SELECT *

FROM ContactsWHERE Id = ?

•GET /Contacts/{id}/Accounts‒ SELECT A.*

FROM Accounts A, Contacts C

WHERE C.Id = ? AND A.Id = C.AccountId

•GET /Contacts/{id}/Opportunities‒ SELECT O.*

FROM Opportunities O

WHERE O.ContactId = ?


Opportunities REST API for Sample Application

•GET /Opportunities‒ SELECT *

FROM Opportunities

•GET /Opportunities/{Id}‒ SELECT *

FROM OpportunitiesWHERE Id = ?

•GET /Opportunities/{id}/Accounts‒ SELECT A.*

FROM Accounts A, Opportunities O

WHERE O.Id = ? AND A.Id = O.AccountId

•GET /Opportunities/{id}/Contacts‒ SELECT C.*

FROM Opportunities O, Contacts C

WHERE O.Id = ? AND O.ContactId = C.Id


Delete REST Operations for Sample Application

•DELETE /Accounts/{Id}‒ DELETE

FROM AccountsWHERE Id = ?

•DELETE /Contacts/{Id}‒ DELETE

FROM Contacts

WHERE Id = ?

•DELETE /Opportunities/{Id}‒ DELETE

FROM Opportunities

WHERE Id = ?

•Depending on the relationships, some APIs may need to update thedependent objects to ensure referential integrity

•E.g. A primary contact for an opportunity or account leaving the company


Design a mobile-friendly Web API

18


Key Mobility API Design considerations

Key Constraints

•Mobile devices run on low power; low bandwidth

•Network quality is always changing – can be weak

•User experience needs to be the best at all times

Design Considerations

•Keep your API complete; incomplete ones burden the App

•Keep UI simple and fast

•Most of the time API’s “get” data to be displayed – Start from the UI, not the data

•Payloads‒ Pay attention to consistency and correctness

‒ Ensure your API Payloads return relevant and required information

‒ Avoid HTML, CSS or JavaScript in responses

‒ Start with what you want to display, not the data

•Data Aggregation‒ Avoid overwhelming number of calls to different backends – your API will slow down

if not

‒ Aggregation ideally done at the backend


Key Mobility API Design considerations

•Use Cache Control‒ For responses that can be cached

•What’s the best format for Mobile API?‒ JSON – Growing in popularity; lightweight

� Natural and easy to use from JavaScript

� JavaScript is increasing in popularity for Web apps

‒ XML – Most APIs today use XML; more readable (but that’s a debate)

� More XML APIs registered on programmableweb than JSON

� XML continues to be leading choice of format for APIs

‒ Key: Keep your request and responses simple

� Think about pagination, limits when returning large set of results

� E.g. LinkedIn API – uses start and count parameters


Implementing Caching for your API

21


Implement Caching

HTTP headers can contain caching directivesHTTP/1.1 200 OK

Date: Fri, 30 Oct 1998 13:19:41 GMT

Server: Apache/1.3.3 (Unix)

Cache-Control: max-age=3600, must-revalidate

Expires: Fri, 30 Oct 1998 14:19:41 GMT

Last-Modified: Mon, 29 Jun 1998 02:28:12 GMT

ETag: "3e86-410-3596fbbc"Content-Length: 1040

Content-Type: text/html

Caches improve network efficiency, improves scalability, and improves user-perceived performance of your API


Securing your API

23


Security mechanisms for Web APIs

OAuth

•Enables users to allow web

applications to access other web applications on the user’s behalf

Basic Auth•Passes Username and password with the

request

•Defined by the HTTP specification

•Uses HTTP Header “Authorization”

•Uses encoding, no encryption

API Keys•Not based on any standard

•Service Provider decides implementation

•Keys act like signatures


Security Mechanisms - OAuth

“The OAuth 2.0 authorization framework enables a third-party application to

obtain limited access to an HTTP service, either on behalf of a resource

owner by orchestrating an approval interaction between the resource

owner and the HTTP service, or by allowing the third-party application to

obtain access on its own behalf”

FourSquare

Twitter

Steve, logged on Foursquare, wants to update his holiday location and also post the same on his Twitter page

Twitter provides an access token to Foursquare that provides access to Steve’s twitter page

Forsquare uses access token provided by twitter to make a post on twitter on Steve’s behalf

Access token (n

o user id/password) re

quired


Security Mechanisms - OAuth


Basic Auth

•Must use SSL if you opt for Basic Authentication‒ Username and Password transmitted in clear text

‒ Base64 encoded, not encrypted

•Pros‒ Easy implementation task for clients

� Part of nearly every HTTP request library

‒ Simple Server setup

� Use existing BasicAuth credentials

•Cons‒ Username password is a must

‒ No default encryption of credentials

‒ Requires user name and password to be embedded in client code


API Keys

•By far the most popular mechanism followed by API Management solutions

•Enables establishing identity of the invoking application - No key? No access

•Enables metering, statistics and accounting – also chargeback

•Implementation not based on any standard – API provider can have proprietary

implementation

•Basics‒ Key is part of URL (how to is described in API documentation)

‒ For e.g. http://myapiprovider.com/api?appId=asf1231ssdfwrwe

•Pros‒ Easy key generation and distribution

‒ No username and password required in raw form

•Cons‒ Unsigned

‒ Must embed them in code

‒ Transmitted in plain text

Best Practices•Use signed requests over unsigned •One key per application per developer

•Require username in headers


Managing and advertizing your APIs

What needs management? How to manage?

API and Resource URLs Use configuration tools to make modifications

and enhancements

API Keys Registration and on-board developer portal tools

to create keys and change secrets

App Developers •Communicate downtime

•Block abusing developer

•Email developers

Developer Portal Updates after changing or adding more

functionality to APIs

Versioning Set versions; Publish new capability

•Where do developers hang out?‒ Forums

‒ Social Networking sites

•Conduct hackathons & App Development competitions

•Popular API directories‒ programmableweb.com

‒ DeveloperWorks


Summary

•Key Concepts – Use REST; consider OAuth, Basic Auth,

•Types of API exposure and considerations

•Design considerations for REST Based API

•Mobility API design considerations

•API Security – OAuth, Basic Auth, API Keys

•Managing and advertising API


Expanding to APIs – IBM Services has the Expertise to Ensure Your Success

3

1

• What should my API Strategy be?

• How are APIs being used in my industry?• What is needed to expose and manage APIs?

• What security do I need?

• Who are my target developers?

• How do I delivery and measure business value?

• How do I get IBM API Management setup quickly?

• Help me design my APIs?• How do I expose my backends as APIs?

• Help me secure and scale my APIs?

• How do I deliver reports to my management?• How do I integrate with existing infrastructure?

API Centric Architecture Assessment Roadmap

IBM Software Services for API Management

For more information contact us at [email protected]


• Emerging technology resources including proven, prescribed, and repeatable assets & offerings to accelerate Mobile, Cloud, and Smarter Process adoption.

• Access to worldwide skills, capabilities, and education that only IBM Software Services for WebSphere can bring to your project.

• Practitioners’ insight on project trends, best practices and emerging technologies through personal videos, blogs, articles & more.

• Discover defined and proven offerings to get your project started quickly.

ibm.com/websphere/serviceszone/ibm.com/websphere/serviceszone/

Visit us in the Solution Center:

• Services, Support and Education Zone

• Smarter Process Zone

IBM Software Services Zone for WebSphere


We love your Feedback!

Don’t forget to submit your Impact session and speaker feedback!

•Your feedback is very important to us – we use it to improve next year’s conference

•Go to the Impact 2013 SmartSite (http://impactsmartsite/com):

‒ Use the session ID number to locate the session

‒ Click the “Take Survey” link

‒ Submit your feedback


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. • If the text contains performance statistics or references to benchmarks, insert the following language; otherwise delete:

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.

• If the text includes any customer examples, please confirm we have prior written approval from such customer and insert the following language; otherwise delete:All customer examples described are presented as illustrations of how those customers have used IBM products and the results they may have achieved. Actual environmental costs and performance characteristics may vary by customer.

• Please review text for proper trademark attribution of IBM products. At first use, each product name must be the full name and include appropriate trademark symbols (e.g., IBM Lotus® Sametime® Unyte™). Subsequent references can drop “IBM” but should include the proper branding (e.g., Lotus Sametime Gateway, or WebSphere Application Server).

Please refer to http://www.ibm.com/legal/copytrade.shtml for guidance on which trademarks require the ® or ™ symbol. Do not use abbreviations for IBM product names in yourpresentation. All product names must be used as adjectives rather than nouns. Please list all of the trademarks that you use in your presentation as follows; delete any not included in your presentation. IBM, the IBM logo, Lotus, Lotus Notes, Notes, Domino, Quickr, Sametime, WebSphere, UC2, PartnerWorld and Lotusphere are trademarks of International Business Machines Corporation in the United States, other countries, or both. Unyte is a trademark of WebDialogs, Inc., in the United States, other countries, or both.

• If you reference Adobe® in the text, please mark the first use and include the following; otherwise delete:

Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries.• If you reference Java™ in the text, please mark the first use and include the following; otherwise delete:

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.• If you reference Microsoft® and/or Windows® in the text, please mark the first use and include the following, as applicable; otherwise delete:

Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both.• If you reference Intel® and/or any of the following Intel products in the text, please mark the first use and include those that you use as follows; otherwise delete:

Intel, Intel Centrino, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States andother countries.

• If you reference UNIX® in the text, please mark the first use and include the following; otherwise delete:

UNIX is a registered trademark of The Open Group in the United States and other countries.• If you reference Linux® in your presentation, please mark the first use and include the following; otherwise delete:

Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others.

• If the text/graphics include screenshots, no actual IBM employee names may be used (even your own), if your screenshots include fictitious company names (e.g., Renovations, Zeta

Bank, Acme) please update and insert the following; otherwise delete: All references to [insert fictitious company name] refer to a fictitious company and are used for illustration purposes only.


Backup Slides

35

Recommended Practices for Designing a Web API

Technology

Transcript of Recommended Practices for Designing a Web API