APIs Design, Creation and Management

Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

Slide 3

Slide 3 text

Slide 4

Slide 4 text

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. Copyright © William El Kaim 2016 4

Slide 5

Slide 5 text

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 Copyright © William El Kaim 2016 5

Slide 6

Slide 6 text

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 Copyright © William El Kaim 2016 6

Slide 7

Slide 7 text

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 Copyright © William El Kaim 2016 7

Slide 8

Slide 8 text

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.” Copyright © William El Kaim 2016 8

Slide 9

Slide 9 text

Slide 10

Slide 10 text

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 Copyright © William El Kaim 2016 10

Slide 11

Slide 11 text

Slide 12

Slide 12 text

Slide 13

Slide 13 text

Plan • What is REST? The Rise Of Restful APIs • Designing Your API • Describing Your API • Promoting Your API • Managing your API • Best Practices and Lessons Learned Copyright © William El Kaim 2016 13

Slide 14

Slide 14 text

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 Copyright © William El Kaim 2016 14

Slide 15

Slide 15 text

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 Copyright © William El Kaim 2016 15

Slide 16

Slide 16 text

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. Copyright © William El Kaim 2016 16

Slide 17

Slide 17 text

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. Copyright © William El Kaim 2016 17

Slide 18

Slide 18 text

Slide 19

Slide 19 text

Slide 20

Slide 20 text

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 Copyright © William El Kaim 2016 20

Slide 21

Slide 21 text

Slide 22

Slide 22 text

Plan • What is REST? • The Rise Of Restful APIs Designing Your API • Describing your API • Promoting Your API • Managing your API • Best Practices and Lessons Learned Copyright © William El Kaim 2016 22

Slide 23

Slide 23 text

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 Copyright © William El Kaim 2016 23

Slide 24

Slide 24 text

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. Source: Martin Fowler Copyright © William El Kaim 2016 24

Slide 25

Slide 25 text

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. Source: Martin Fowler Copyright © William El Kaim 2016 25

Slide 26

Slide 26 text

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. Source: Martin Fowler Copyright © William El Kaim 2016 26

Slide 27

Slide 27 text

Slide 28

Slide 28 text

Slide 29

Slide 29 text

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. Source: Martin Fowler Copyright © William El Kaim 2016 29

Slide 30

Slide 30 text

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! Source: Martin Fowler Copyright © William El Kaim 2016 30

Slide 31

Slide 31 text

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. Source: Martin Fowler Copyright © William El Kaim 2016 31

Slide 32

Slide 32 text

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! Source: Martin Fowler Copyright © William El Kaim 2016 32

Slide 33

Slide 33 text

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 Copyright © William El Kaim 2016 33

Slide 34

Slide 34 text

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. Source: Martin Fowler Copyright © William El Kaim 2016 34

Slide 35

Slide 35 text

Plan • What is REST? • The Rise Of Restful APIs • Designing Your API Describing your API • Promoting Your API • Managing your API • Best Practices and Lessons Learned Copyright © William El Kaim 2016 35

Slide 36

Slide 36 text

Slide 37

Slide 37 text

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 Copyright © William El Kaim 2016 37

Slide 38

Slide 38 text

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. Copyright © William El Kaim 2016 38

Slide 39

Slide 39 text

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/ Copyright © William El Kaim 2016 39

Slide 40

Slide 40 text

Slide 41

Slide 41 text

Slide 42

Slide 42 text

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. Copyright © William El Kaim 2016 42

Slide 43

Slide 43 text

Slide 44

Slide 44 text

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. Copyright © William El Kaim 2016 44

Slide 45

Slide 45 text

Slide 46

Slide 46 text

Slide 47

Slide 47 text

Slide 48

Slide 48 text

Slide 49

Slide 49 text

Slide 50

Slide 50 text

Slide 51

Slide 51 text

Slide 52

Slide 52 text

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. Copyright © William El Kaim 2016 52

Slide 53

Slide 53 text

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/ Copyright © William El Kaim 2016 53

Slide 54

Slide 54 text

Slide 55

Slide 55 text

Slide 56

Slide 56 text

Slide 57

Slide 57 text

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 Copyright © William El Kaim 2016 57

Slide 58

Slide 58 text

Plan • What is REST? • The Rise Of Restful APIs • Designing Your API • Describing Your API Promoting Your API • Managing your API • Best Practices and Lessons Learned Copyright © William El Kaim 2016 58

Slide 59

Slide 59 text

Slide 60

Slide 60 text

Slide 61

Slide 61 text

Slide 62

Slide 62 text

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) Copyright © William El Kaim 2016 62

Slide 63

Slide 63 text

Slide 64

Slide 64 text

Slide 65

Slide 65 text

Slide 66

Slide 66 text

Slide 67

Slide 67 text

Slide 68

Slide 68 text

Slide 69

Slide 69 text

Slide 70

Slide 70 text

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/ Copyright © William El Kaim 2016 70

Slide 71

Slide 71 text

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. Copyright © William El Kaim 2016 71

Slide 72

Slide 72 text

Slide 73

Slide 73 text

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. Copyright © William El Kaim 2016 73

Slide 74

Slide 74 text

Slide 75

Slide 75 text

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. Copyright © William El Kaim 2016 75

Slide 76

Slide 76 text

Slide 77

Slide 77 text

Plan • What is REST? • The Rise Of Restful APIs • Designing Your API • Describing Your API • Promoting Your API Managing your API • Best Practices and Lessons Learned Copyright © William El Kaim 2016 77

Slide 78

Slide 78 text

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 Copyright © William El Kaim 2016 78

Slide 79

Slide 79 text

Slide 80

Slide 80 text

Slide 81

Slide 81 text

Slide 82

Slide 82 text

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 Copyright © William El Kaim 2016 82

Slide 83

Slide 83 text

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 Source: Robert Broeckelmann Copyright © William El Kaim 2016 83

Slide 84

Slide 84 text

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. Copyright © William El Kaim 2016 84

Slide 85

Slide 85 text

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. Source: Robert Broeckelmann Copyright © William El Kaim 2016 85

Slide 86

Slide 86 text

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 Copyright © William El Kaim 2016 86

Slide 87

Slide 87 text

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". Copyright © William El Kaim 2016 87

Slide 88

Slide 88 text

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) Source: Robert Broeckelmann Copyright © William El Kaim 2016 88

Slide 89

Slide 89 text

Slide 90

Slide 90 text

Slide 91

Slide 91 text

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. Copyright © William El Kaim 2016 91

Slide 92

Slide 92 text

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. Copyright © William El Kaim 2016 92 Source: Tom Johnson

Slide 93

Slide 93 text

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 Copyright © William El Kaim 2016 93 Source: Tom Johnson

Slide 94

Slide 94 text

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. Copyright © William El Kaim 2016 94 Source: Tom Johnson

Slide 95

Slide 95 text

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 Copyright © William El Kaim 2016 95 Source: Tom Johnson

Slide 96

Slide 96 text

API Security: OAuth 2.0 • 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. Copyright © William El Kaim 2016 96 Source: Tom Johnson

Slide 97

Slide 97 text

Slide 98

Slide 98 text

Slide 99

Slide 99 text

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 Copyright © William El Kaim 2016 99

Slide 100

Slide 100 text

Slide 101

Slide 101 text

Slide 102

Slide 102 text

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. Copyright © William El Kaim 2016 102

Slide 103

Slide 103 text

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 Copyright © William El Kaim 2016 103

Slide 104

Slide 104 text

Plan • What is REST? • The Rise Of Restful APIs • Designing Your API • Describing Your API • Promoting Your API • Managing your API Best Practices and Lessons Learned Copyright © William El Kaim 2016 104

Slide 105

Slide 105 text

Slide 106

Slide 106 text

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 Copyright © William El Kaim 2016 106

Slide 107

Slide 107 text

Slide 108

Slide 108 text

Slide 109

Slide 109 text

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 Copyright © William El Kaim 2016 109

Slide 110

Slide 110 text

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 Copyright © William El Kaim 2016 110

Slide 111

Slide 111 text

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 Copyright © William El Kaim 2016 111

Slide 112

Slide 112 text

Slide 113

Slide 113 text

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 Copyright © William El Kaim 2016 113

Slide 114

Slide 114 text

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 Copyright © William El Kaim 2016 114