APIs Design - Creation - Management.pdf

APIs Design, Creation
and Management
William El Kaim
Oct. 2016 - V 2.2

This Presentation is part of the
Enterprise Architecture Digital Codex
http://www.eacodex.com/
Copyright © William El Kaim 2016 2

Plan
What is REST?
• The Rise Of Restful APIs
• Designing Your API
• Describing You API
• Promoting Your API
• Managing your API
• Best Practices and Lessons Learned

What is REST?
• REST stands for representational state transfer, meaning that a client
communicates with a server and not directly with the source of information
on that server.
• This transfer is done through representations of the state of that resource.
• The REST architectural style for distributed systems was developed around
2000, and it is patterned after the HTTP/1.1 Protocol.
• In RESTful designs, the client does not need to know about the
implementation on the server.
• The server is free to store data as it likes, and the client can store the same information
differently.
• This loose coupling means that as long as the interface is stable, the
implementation on the client or the server can independently change.

REST architectural style is Based on Six Principles
1. Client/server loose coupling
• A clean separation of duty exists between client and server.
• The type of data storage does not matter to the client, and the client interface or client
state does not matter to the server.
• With a stable interface, the client and server may be developed and replaced
independently of each other.
2. Stateless
• The interface that dictates how the client and server interact does not allow client states
to be stored on the server.
• Information about client states is embedded in the messages the clients send to servers.
3. Cacheable
• Clients can have the ability (and must let the server know whether they do or not) to
temporarily store data received from the server.
Source: PWC

REST architectural style is Based on Six Principles
4. Layering
• Servers do not know whether there are layers of abstraction between themselves and
the end client
• For example, whether they are passed through multiple security policies, APIs, and so forth.
5. Code on demand
• Servers are able to temporarily send custom functions as executable code to clients for
them to execute.
6. Uniform interface
• Servers and clients can interact, change, and be modified independently as long as the
interface that binds them remains the same.
Source: PWC

From REST to Restful …
• An API implemented using the preceding principles of REST and using
standard HTTP communications protocols is a RESTful API,
• sometimes called a RESTful web service
• Like any resource on the web, the RESTful API will need a Uniform
Resource Identifier (URI), such as an http:// address.
• RESTful API developers are increasingly using REST in conjunction with
JSON

RESTful APIs Are Also Called Web API
• Web API is described as:
• “A set of Hypertext Transfer Protocol (HTTP) request messages, along with a definition
of the structure of response messages, which is usually in an Extensible Markup
Language (XML) or JavaScript Object Notation (JSON) format.”
• Hence a Web API can be defined without the technical specifics as:
• “An interface to a software component that can be invoked at a distance over a
communications network using standards based technologies.”

REST and RESTful Synthesis

Entering JSON
• JSON is a resource-based data transfer mechanism, to further simplify the
process of communication between the information seeker (the client), and
the system containing the information to be consumed (the server).
• JSON is derived from the JavaScript scripting language, which is widely
used in web browsers to enhance interfaces and build dynamic websites.
• Like REST, JSON is noted for its simplicity and usability
• With JSON, data is sent in plain text, which makes it easy to read and understand.
• Because so many web client programs are written in JavaScript, JSON data
arrives ready to be consumed without needing further manipulation.
• At the same time, JSON lacks display capabilities and has a limited amount of
development tool support.
Source: PWC

JSON vs. HTML
Compact and easy to process

RESTful Architecture and REST Languages

Plan
• What is REST?
The Rise Of Restful APIs
• Describing Your API

APIs and Coupling
• API is a mechanism for linking programs since the early days of software.
• However, API creation and design have significantly changed.
• Early methods were proprietary and created interdependent coupling among pieces of
code and systems. If one side of the coupling required a code change, the other side
was affected.
• Over time, APIs evolved to reduce the interdependency of tightly coupled interfaces,
generally lowering the complexity of integration.
Source: PWC

The rise of RESTful APIs
• Within the last decade, enterprises began to expose APIs to allow external
parties to build new functionality
• Service-oriented architecture (SOA), which gained wide acceptance using
web services built on SOAP, has been popular within organizations as a
mechanism for sharing information across the enterprise.
• Today, communication on the web has evolved from the early days of using
SOAP standards to using features of RESTful methods, making REST-
compliant APIs a major class of web services.
• However, the use of a REST architecture, along with associated
technologies such as JavaScript Object Notation (JSON), is accelerating the
development and use of APIs.
Source: PWC

SOAP vs. REST
• For many enterprises, the path to web services began with the adoption of a
service-oriented architecture (SOA), using SOAP as a protocol for
exchanging information.
• In today’s web service world, both SOAP and REST are used as methods of
communication.
• There are several factors behind the popularity of REST when contrasted
with SOAP.
• REST uses simple HTTP and therefore standard commands—such as GET, PUT, POST,
and DELETE—to coordinate communication between clients and servers.
• SOAP has no widely accepted methods corresponding to GET, PUT, POST, and
DELETE, which leaves developers free to define their own semantics. But the result can
be complex, proprietary mechanisms to connect components.

SOAP vs. REST
• Familiarity
• Since REST is closely related to web design, web developers do not face a steep
learning curve. REST is also language and platform agnostic.
• SOAP requires a significant skill set in SOA-specific development and delivery tools.
• Efficient with bandwidth
• The use of the existing web infrastructure eliminates the need for an additional
messaging layer in RESTful APIs. Coupled with the fact that REST uses those short
request and response sequences, these APIs consume considerably less bandwidth
than SOAP-based APIs.
• Scalability
• With simpler component implementations and reduced complexity in the connection
semantics, RESTful services can scale—as evident from several services that register
more than 1 billion API calls each month.

SOAP vs. REST
Source: PWC
REST is leveraging HTTP!

SOAP vs. REST …
SOAP is Chatty!

The rise of RESTful APIs: Why Now?
• APIs are becoming the basis for creating digital value chains, including
digital indirect channels previously established mainly by software
companies and purely web-based companies.
• One big reason behind the successful adoption of RESTful APIs is
developers’ ability to build modular capabilities with lightweight interfaces
that don’t require heavy integration.
• “RESTful interfaces create a level of simplicity that didn’t exist previously, and simplicity
always speeds things up, making integrations cost-effective,” says John Musser, founder
of ProgrammableWeb.
• Key tools for participating in the digital economy are now:
• A relatively new style of APIs, called representational state transfer (RESTful) APIs, and
• Solutions to manage them, called API management platforms
Source: PWC

API Protocols and Styles

Plan
• What is REST?
Designing Your API
• Describing your API

Designing Your API
• To design your REStful API, use the Richardson Maturity Model
• Level 0: HTTP as a transport system for remote interactions
• Level 1: Resources
• Level 2: HTTP Verbs
• Level 3: Hypermedia Controls
Source: Martin Fowler

Level 0: HTTP As A Transport System
• The starting point for the model is using HTTP as a transport system for
remote interactions, but without using any of the mechanisms of the web.
• Using HTTP as a tunneling mechanism for remote interaction mechanism, usually based
on Remote Procedure Invocation.
RPC style system is simple and use plain old XML back and forth!
For SOAP or XML-RPC, it's basically the same mechanism, the only
difference is the wrapping of the XML messages in some kind of envelope.

Level 1 - Resources
• The first step towards the Glory of Rest is to introduce resources.
• So now rather than making all requests to a singular service endpoint, start
talking to individual resources.

Level 2 - HTTP Verbs
• Using the HTTP verbs as closely as possible to how they are used in HTTP
itself.
• HTTP defines GET as a safe operation (ie. it doesn't make any significant changes to the
state of anything). Invoking GETs any number of times in any order should get the same
results each time.
• Any participant in the routing of requests can then use caching, which is a key element in
making the web perform as well as it does.

Level 2 - HTTP Verbs - Example
Source: 3Scale

HTTP Status Code Map
Source: Restlet

Introduction to HATEOAS
• Hypertext As The Engine Of Application State (HATEOAS) is a constraint of
REST.
• The principle is that a client interacts with a network application entirely
through hypermedia provided dynamically by application servers.
• A REST client needs no prior knowledge about how to interact with any particular
application or server beyond a generic understanding of hypermedia.
• In a service-oriented architecture (SOA), clients and servers interact through a
fixed interface shared through documentation or an interface description language (IDL).
• RESTful service can be described as well to be available for the client code-generation
using the RESTful Service Description Language (RSDL).
• The HATEOAS constraint serves to decouple client and server in a way that
allows the server to evolve functionality independently.

Level 3 - Hypermedia Controls
• The final level introduces HATEOAS
• Hypermedia controls tell us what we can do next, and the URI of the
resource we need to manipulate to do it.
• Rather than us having to know where to post our appointment request, the hypermedia
controls in the response provide information about how to do it!

Level 3 - Hypermedia Controls
• One obvious benefit of hypermedia controls is that it allows the server to
change its URI scheme without breaking clients.
• A further benefit is that it helps client developers explore the protocol.
• The links give client developers a hint as to what may be possible next.
• Similarly it allows the server team to advertise new capabilities by putting
new links in the responses.
• If the client developers are keeping an eye out for unknown links these links can be a
trigger for further exploration.
• There's no absolute or “de facto” standard as to how to represent
hypermedia controls.

Using Hypermedia-Style Messages to Build
Flexible, Durable APIs
• With a Hypermedia API, the API will use a registered media type such
as HAL or Collection-JSON, providing a common framework for developers
to communicate with the API
• Reducing the unknowns in API integration.
• Two major options for a hypermedia type.
• Use an existing type: XHTML, Collection+JSON, HAL, Siren
• Build your own
• Two paths: Make a custom type, or use the profile link relation.
• If you'd like to make a custom type, read Building Hypermedia APIs in HTML5 and Node.
Building a custom type is just as much art as science.
• Read this blog post from Kevin Sookocheff to know more!

Examples of Hypermedia APIs
• Amazon AppStream REST API
• Manage applications hosted on Amazon AppStream and to manage client sessions
connecting to those applications.
• Foxy HAPI
• A hypermedia example from the world of commerce.
• FamilySearch
• Discovering and managing your family history.
• Huddle
• An enteprise example of hypermedia APIs from the content collaboration platform
huddle.
• PayPal REST API
• One of the key features of the PayPal REST API is HATEOAS
• VerticalResponse
Source: API evangelist

Synthesis
• The Richardson model helps designing the HTTP service to be provided and
frames the expectations of people looking to interact with it.
• It’s up to you to choose up to which level you want your API to conform to:
• Level 1 tackles the question of handling complexity by using divide and conquer,
breaking a large service endpoint down into multiple resources.
• Level 2 introduces a standard set of verbs so that we handle similar situations in the
same way, removing unnecessary variation.
• Level 3 introduces discoverability, providing a way of making a protocol more self-
documenting.

Plan
• What is REST?
Describing your API

Describing your API via Web API Languages

Web Api Languages
• Can describe Web APIs
• XML or JSON driven representations
• Proper HTTP methods usage
• Markup languages (XML, JSON, YAML, markdown)
• Can generate code
• Client SDKs and Server Skeleton
• Several competing languages
• Swagger - most popular description format for defining Restful APIs.
• RAML (RESTful API modeling language)
• Api Blueprint
• Google API Discover Service
• JSON API
• And API Transformer
• Transform API Descriptions from/to various formats

Swagger
• Swagger is a specification and complete framework implementation for
describing, producing, consuming, and visualizing RESTful web services.
• Swagger is language agnostic.
• Swagger-enabled API, allows you to get interactive documentation, client SDK
generation and discoverability.
• The Swagger specification allows you define a set of files to describe an
API.
• Using these files, the Swagger-UI project could display the API and Swagger-Codegen
could generate clients in various languages.
• The Swagger Ecosystem provides support for various tooling built both by
external parties and the developers of the Swagger specification.

Open API (OAI)
• Starting January 1st 2016 the Swagger Specification has been donated to to
the Open API Initiative (OAI) and has been renamed to the OpenAPI
Specification.
• Starting with version 2.0 of the Swagger Specification, the OAI will be
involving API consumers, developers, providers, and vendors alike to build
the most useful, comprehensive specification possible.
• The goal of the OAI specification is to define a standard, language-agnostic
interface to REST APIs which allows both humans and computers to
discover and understand the capabilities of the service without access to
source code, documentation, or through network traffic inspection.
• Resources:
• GitHub: https://github.com/OAI/OpenAPI-Specification
• Site: https://openapis.org/

Open API (OAI) version 3.0
Source: OpenAPI

Swagger Tool (SmartBear)
http://swagger.io/

RAML
• RAML is a language for the definition of HTTP-based APIs that embody most
or all of the principles of Representational State Transfer (REST).
• The RAML specification defines an application of the YAML
1.2 specification that provides mechanisms for the definition of practically-
RESTful APIs, while providing provisions with which source code generators
for client and server source code and comprehensive user documentation
can be created.
• RAML to HTML is a documentation tool and it outputs a single HTML page console
based on a RAML definition. It's written in NodeJS and it can be executed as a
command line. The project is an opensource project and could be customized on a need
basis.
• RAML is also extremely popular and has a rich ecosystem of tooling built
around RAML available.

RAML (MuleSoft)
http://raml.org/

API Blueprint
• API Blueprint is a documentation-oriented web API description language.
• The API Blueprint is essentially a set of semantic assumptions laid on top of
the Markdown syntax used to describe a web API.
• The format is open sourced and lot of tooling including code generators,
editors are provided by Apiary.io.

API Blueprint (Apiary)
https://apiblueprint.org/

Google API Discovery Service
https://developers.google.com/discovery/

JSON API
http://jsonapi.org/

API Transformer
https://apitransformer.com/

High Level Comparison
Source: Dzone

Describing Your API With a Tool
https://stoplight.io/

Describing Your API With a Tool
https://www.mulesoft.com/platform/api/anypoint-designer

API Commons
• APIs are transforming the web in radical new ways are clearly leading a
great deal of innovation and value
• This rapid growth however also brings with potentially huge costs
• namely the need to create client (and server) code for potentially hundreds of thousands
or millions of unique, slightly different APIs.
• While there are some solutions to help reduce this cost (automated code
generation, or more flexible intelligent client code) the unlikely to make much
of a dent in the overall problem in the short and mid term.
• A further problem is that, despite recent copyright victories, the reuse of API
interfaces (the definitions of them / data models / call partners etc.) remain a
legal grey area and reuse of interface patterns may result in legal risks.

What If API Definitions Were Actually Explicitly
Open And Shareable?
• API Commons proposes to encourage API designers to declare APIs the
produce to be "In the Commons" much the way creative work can be
licensed under Creative Commons or code can be open sourced.
• Initiative from Kin Lane the API Evangelist
• The objective of doing this is to:
• Make it explicit when an API in whole or part could be re-used
• Over time build up a valuable set of reusable API interface resources
• The most popular of which may in turn encourage shared development of shared client
(or server) code
• Remove legal risk from API Interface design reuse
• Dedicated web site: http://apicommons.org/

Example

Finding and Testin REST APIs
REST client
• Apigee Console
• Insomnia
• Paw (for Mac Only)
• Postman and “Run in Postman”
button
• Quadrillian
• RestClient.net
• SoapUI
• Tibco ActiveMatrix BusinessWorks
V6
Searching for Open APIs
• Apis.io
• Api for That
• Mashape marketplace
• Programmable Web

Plan
• What is REST?
Promoting Your API

Register Your API in Public Repository
• Apis.io
• Api for That
• Mashape marketplace
• Programmable Web

Create and Grow Your Ecosystem

What’s Needed?

Invest in Developer Experience (DX)
• Developer Experience is to developers what User Experience (UX) is to
users.
• Refers to developer experiences integrating with an API, from the front-end, portal and
key retrieval experience, down to back-end data integration.
• You also need a developer evangelist
• A developer evangelist is a spokesperson, mediator and translator between a company
and both its technical staff and outside developers.
• Resources
• developerexperience.org
• see also developer-support-handbook.appspot.com
• Developer Experience: The UX of APIs from Jeremiah Lee
• Mashery DX Certified API
• Pamela Fox (Youtube and Slideshare presentation)

Create a Dedicated Dev. Portal
https://gelato.io/
Gelato from Mashape
(open source)

Create a Dedicated Portal

Make Great Documentation

Provide Code Samples & SDK

Generate SDK
Source: APImatic

Provide Easy to Use Tools

Build Your Marketplace

Organize Hackathons
• A hackathon (also known as a hack day, hackfest or codefest) is an event in
which computer programmers and others involved in software development
collaborate intensively on software projects.
• Hackathons typically last between a day and a week.
• Some hackathons are intended simply for educational or social purposes (creating
community of users), although in many cases the goal is to create usable software.
• Hackathons tend to have a specific focus, which can include
the programming language used, the operating system, an application,
an API.
• Example
• http://apihackday.com/

Organize Meetups
• The noun
• Regular (or more spontaneous) face-to-face meetings of Wikipedians take place in cities
around the world.
• The service
• Meetup is an online social networking portal that facilitates offline group meetings in
various localities around the world.
• Meetup allows members to find and join groups unified by a common interest, such as
politics, books, games, movies, health, pets, careers or hobbies.
• Users enter their postal code or their city and the topic they want to meet about, and the
website helps them arrange a place and time to meet.
• Topic listings are also available for users who only enter a location. Meetup receives
revenue by charging Organizer Dues to administrators of groups, currently at $12 to $19
per month depending on the payment plan.

Organize Meetups
http://www.meetup.com/

Keep The Conversations Going
• Use standard and dedicated to developer collaboration and social tools to
ease discussions with developer
• GitHub
• GitHub is a web-based hosting service for software development projects.
• Geeklist
• Geekli.st is an achievement-based social portfolio builder for developers where they can
communicate with colleagues and employers and build credibility in the workplace.
• Stackoverflow
• Stack Overflow is a free programming Q & A site. Stack Overflow is collaboratively built
and maintained by its members.

Participate to Developer Communities
https://coderwall.com/

Facilitate Reuse
Widgets, Mini Apps, And Enterprise Mashups.
• itDuzzit makes it easy to create alerts, widgets, mini apps, and enterprise
mashups.
• Leverage content from popular web sites and services, configure intelligent
apps, and push cloud content to any web site, platform, social media, email,
SMS, and phone.

DX Example: DreamFactory
https://www.dreamfactory.com/

Plan
• What is REST?
Managing your API

What about API Delivery?
• As organizations become determined to publish APIs as part of their Internet
infrastructure and application strategies, they learn that simply putting an API
up for use by others is not entirely too complex.
• However, they also discover that publishing a reliable, secure, enterprise-
grade API to a controlled audience with high levels of performance that have
the ability to scale with adoption can be quite a serious undertaking.
• These kinds of requirements are why the API Management space has
emerged to the forefront.
• Need
• Solutions for publishing APIs, creating and managing a developer community and for
scalable routing API traffic

How to Manage API Delivery?

API Management Is Now Required!

API Management
• API Management solution manages and governs the use of APIs to open up
an organization or a system’s data so that it can be utilized by other parts of
the organization or possibly third-party organizations in new and useful
ways.
• A for-profit organization would use these capabilities to either create new revenue
streams of revenue or enhance/optimize existing revenue streams (monetizing APIs)
• A non-profit organization or government organization may be trying to cover its
operational costs while fulfilling its mission to provide benefit (in this case, in the form of
data/information) to the public.
• API Management should provide an easy, effective, and efficient experience
for the development community that is supposed to be using those APIs.
• API Management also provides a governance and life-cycle framework for
APIs.
Source: Robert Broeckelmann

API Management Scope
• The process of publishing, promoting, and overseeing APIs in a secure,
scalable environment
• Ensuring that developers and partners are productive
• Managing, securing, and mediating your API traffic
• Allowing an organization to grow their API program to meet increasing
demands
• Enabling the monetization of APIs
• The intersection of technology, business, organization, and integration
concerns

API Mgt: Why Now?
• Urgent need to Facilitate API Adoption, Documentation and Management
since:
• The proliferation of SaaS applications and integration requirements has contributed
significantly to the interest in API Management.
• Legacy applications moving to the Cloud and the need to pass messages and data
between these applications
• Explosion in mobile devices, tablets, other smart devices, and apps have been major
factors.
• Couple of large acquisitions and increasing investments occurring in the
space.
• Many SOA (Service Oriented Architecture) and other infrastructure vendors have re-
invented themselves as API Mgt solutions.

API Mgt Models
• Every API Management solution contains three components:
• API Gateway: run-time component of the API Management solution. All API requests are
directed through this layer of the system. It is the front door for all API traffic and the
processing policies defined by the administrator are enforced here.
• Developer Portal: central point of engagement for the development community using
your organization’s APIs. The developers using the portal could be inside your
organization, in different lines of business, from business partners, or third parties who
use your APIs in their products.
• Management Portal: drives the activities and capabilities of the other two. The
Management Portal allows administrators to define APIs, deploy APIs, and promote APIs
through the environments. It allows for the definition of environments such as dev, test,
and production. How the environment concept is implemented varies between vendor
products.

API Management Models
• Proxy model
• You have to provide an API endpoint address exposed on the Internet
• Aka. have an existing, functional API in place and in a production setting.
• The vendor will wrap your API to offer user management and authentication, report
usage statistics, and provide other features such as support for multiple protocols like
SOAP, REST, and JSON.
• Fully-hosted API Model
• Data, software, or other assets provided will be expressed as an API, and the vendor will
deploy all of it within its own infrastructure, allowing you to remotely manage and
administrate access and availability to that API.
• This includes all of the user management, reporting and other features that you would receive
in the proxy model.
• Scalability, multi-tenancy, performance, reliability, ongoing monitoring, and security are
all abstracted away from you.
• No need to have a team of API infrastructure experts available on your staff to monitor
and manage the ongoing usage of your APIs

API Mgt: Proxy Model Drawbacks
• Proxy model still requires you to manage the infrastructure and the software
and data behind your API.
• This includes the unpredictable cost and investment required to scale upon increases in
adoption.
• You must also build in the ability to fail-over when necessary (such as server
or database failures), ensure performance and reliability, and essentially
mirror the infrastructure requirements of the API Management vendor.
• This approach also increases the potential points of failure, as both you and
your API Management vendor must have consistent, high-performance and
reliable uptime numbers simultaneously.
• This can also be an additional challenge, because if either one of you
experience a spike in traffic, you are essentially "down".

API Mgt: API Governance
• API Governance addresses:
• Tracking The Life-cycle Of Each API From Inception To Sun-setting (More Below)
• Tracking The API Consumers And Subscriptions (Relationships)to Apis Utilized
• The API Security Model Employed And The Details Of Managing It
• Defines The API Interface Standards Used For Creating Apis (An Organization’s Standards For
Usage Of Something Like Swagger) In The Organization
• Gathering Statistics Of Both The Developer Portal And API Gateway Usage
• Utilization-based Billing
• API Versioning
• JSON (Or XML) Schema Versioning For Input And Output Data Structures
• Tracking Of Routing Information
• API Governance must tie into:
• Change Management
• Asset Management
• Configuration Management
• Legacy SOA Governance (with the goal of eventually replacing it)

API Mgt: Capabilities
Source: PWC

API Mgt: API Versioning?

API Mgt: API Security?
• Before users can make requests with Open API, they’ll usually need to
register for some kind of application key, or learn other ways to authenticate
the requests.
• APIs vary in the way they authenticate users. Some APIs just require to
include an API key in the request header, while other APIs require elaborate
security due to the need to protect sensitive data, prove identity, and ensure
the requests aren’t tampered with.
• Common forms of authentication and authorization with APIs include Basic
Auth, HMAC, and OAuth 2.0.

API Security: API keys
• An API key is a usually a long string that you include either in the request URL or
in the request header.
• The API key mainly functions as a way to identify the person making the API call
(authenticating you to use the API). The API key is associated with a specific app
that you register.
• The company producing the API might use the API key for any of the following:
• Authenticate calls to the API to registered users only
• Track who is making the requests
• Track usage of the API
• Block or throttle requesters who exceed the rate limits
• Apply different permission levels to different users
• Sometimes APIs will give you both a public and private key. The public key is
usually included in the request, while the private key is treated more like a
password and used only in server-to-server communication.
Source: Tom Johnson

API Security: Basic Auth
• Authorization method where the sender places a “username:password” into
the request header.
• The username and password is encoded with Base64
• APIs that use Basic Auth will also use HTTPS, which means the message content will be
encrypted within the HTTP transport protocol.
• When the API server receives the message, it decrypts the message and
examines the header. After decoding the string and analyzing the username
and password, it then decides whether to accept or reject the request.
• Example of a Basic Auth in a header
• Authorization: Basic RnJlZDpteXBhc3N3b3Jk
Source: Tom Johnson

API Security: HMAC
• HMAC stands for Hash-based Message Authorization Code
• Stronger type of authentication than Basic Auth
• With HMAC, both the sender and receiver know a secret key that no one else
does.
• The sender creates a message based on some system properties (for example, the request
timestamp plus account ID).
• The message is then encoded by the secret key and passed through a secure hashing
algorithm (SHA). The resulting value, referred to as a signature, is placed in the request
header.
• When the receiver (the API server) receives the request, it takes the same system properties
(the request timestamp plus account ID) and uses the secret key (which only the requester and
API server know) and SHA to generate the same string. If the string matches the signature in
the request header, it accepts the request. If the strings don’t match, then the request is
rejected.
• The important point is that the secret key (critical to reconstructing the hash) is
known only to the sender and receiver. The secret key is not included in the
request.
• HMAC security is used when you want to ensure the request is both authentic
and hasn’t been tampered with.
Source: Tom Johnson

API Security: OAuth 2.0
• OAuth 2.0 is becoming the de facto standard for API security.
• This approach relies upon an authentication server to communicate with the
API server in order to grant access.
• You often see OAuth 2.0 when you’re using a site and are prompted to log in using a
service like Twitter, Google, or Facebook.
• There are a few varieties of Oauth
• “one-legged OAuth”: retrieves general, read-only information (such as news articles).
One-legged OAuth is used when you don’t have sensitive data to secure.
• “three-legged OAuth.” Used when you need to protect sensitive data. Complex protocol
involving three interacting stakeholders:
• The authentication server
• The resource server (API server)
• The user or app
Source: Tom Johnson

• The consumer application sends over an application key and secret to a
login page at the authentication server. If authenticated, the authentication
server responds to the user with an access token.
• The access token is packaged into a query parameter in a response redirect
(302) to the request. The redirect points the user’s request back to the
resource server (the API server).
• The user then makes a request to the resource server (API server). The
access token gets added to the header of the API request with the word
Bearer followed by the token string. The API server checks the access token
in the user’s request and decides whether to authenticate the user.
• Access tokens not only provide authentication for the requester, they also
define the permissions of how the user can use the API. Additionally, access
tokens usually expire after a period of time and require the user to log in
again.
Source: Tom Johnson

Source: SAP

API Mgt: API Security?

API Mgt: Tool Vendors
• 3scale bought by RedHat
• Axway 5
• Amazon API gateway
• Anypoint by Mulesoft
• Apiary.io
• Apigee bought by Google
• ApiMint
• ApiSpark from Restlet
• Akana
• Azure API
• Google Cloud Endpoints
• Layer 7 bought by CA
• Mashery bought by Tibco
• Strikeiron bought by Informatica
• WSO2 API Cloud
• ApiAxle
• Apihub
• API man by Redhat
• ApiTools from 3Scale
• API Umbrella
• Dreamfactory
• Fusio
• Kong from Mashape
• Monarch API mgt
• Repose from RackSpace
• Swagger
• Tyk
• WSO2 API Mgt and
Open Source
Commercial

API Mgt: DreamFactory
https://www.dreamfactory.com/

API Mgt Tool Vendors

API Mgt Tools
• Reverse Proxys
• Traefik - can run in container
• HAProxy
• Nginx / Nginx Commercial
• Varnish API Engine
• API Security
• Vaddy: security scanner
• Stormpath: provides authentication
and user management for developers.
• Command Line Tools
• Curl / HTTPie /
• API Testing
• Restlet DHC
• SoapUI (Desktop / Open Source &
Professional)
• SpotLight
• The Right API (Cloud)
• API Monitoring
• APIScience
• PagerDuty: monitoring through alerts
via SMS, phone, email, iOS
or Android.
• Runscope offers a service for
monitoring API traffic.

API Mgt Tools
• Turn Your spreadsheets into
APIs
• BlockSpring
• CalcFusion
• Dreamfactory
• SheetLabs
• API documentation
• DocBox (open source)
• Lucybot
• Readme.io
• Slate (open source)
• API Development Studio
• API Workbench
• Atom Editor
• Codenvy
• Kite
• Reprezen
• Sublime HQ
• Visual Studio
• API Full Lifecycle Mgt.
• IBM API Connect (ex: Strongloop)
• SwaggerHub

Plan
• What is REST?
Best Practices and Lessons Learned

Adopt a Layered Approach

Your API in Three Steps
1. Identify resources, and their hierarchy
2. Design the API
• Choose HTTP verbs, headers, and status code
• Choose media types and hypermedia links
• Choose wisely resource naming, and API security mechanism
• Define a versioning strategy
• Code and test
3. Publish, Promote and Evangelize
• Create an API marketing plan
• Create a dedicated web site and leverage DX
HTTP status code in short

ETSY Example
API
API
API

Five Keys To Great API

Be Remixable So That Your API Is Recombinant!
• REST first, everything else second
• Nothing weird: straight XML, straight JSON
• Keep responses small
• Keep calls granular
• No custom security schemes: use OAuth
• Don’t make the developer deal with PCI-compliance
• Sample code wins every time
• You’ll get it wrong the first time – so listen well

Nouns and verbs
• Prefer nouns to verbs
• nouns refer to resources
• resources are handled with HTTP verbs
• Verbs can be used for actions or calculations
• /login, /logout, /convertTemperature
• Prefer plural forms
• /tickets/234 vs /ticket/234
• Prefer lowercase, and underscore for naming

Tips To Avoid Pitfalls
• Define revenue value chain
• Deploy "sense and respond" and innovation toolkits rather than applications with fixed
functionality
• Propose several business models
• Adapted for multiple distribution channels
• Think DATA (Stop thinking Application/IT product)
• Adopt a flow based vision where real time data is valorised
• Implement Open API
• Invest on Business Analysis for finding the most valuable travel services to offer /build.
• Enhance User Experience
• Let users select their best in class solutions for each delivery channel

Never Forget !!!

Resources
• ProgrammableWeb API university
• Matthias Biehl API University and its Books
• Apigee Academy
• 3Scale API Codex
• Nordic APIs
• Kin Lane, The API evangelist and it "API deployment guide"
• Octo Technology "How to design a RESTful API" and the "Design Reference
Card"
• A Practical API Design Framework: Noun As Resource With HyperLinks
(NARWHL)
• Writing OpenAPI specification Tutorial
• HTTP Status Code Map

Twitter
http://www.twitter.com/welkaim
SlideShare
http://www.slideshare.net/welkaim
EA Digital Codex
http://www.eacodex.com/
Linkedin
http://fr.linkedin.com/in/williamelkaim
Claudine O'Sullivan

APIs Design - Creation - Management.pdf

More Related Content

Similar to APIs Design - Creation - Management.pdf (20)

Recently uploaded (20)

APIs Design - Creation - Management.pdf