APIs Design, Creation and Management

APIs Design, Creation and Management

Transcript

1. APIs Design, Creation and Management William El Kaim Oct. 2016 - V 2.2
2. This Presentation is part of the Enterprise Architecture Digital Codex http://www.eacodex.com/ Copyright © William El Kaim 2016 2
3. 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 Copyright © William El Kaim 2016 3
4. 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
5. 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
6. 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
7. 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
8. 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
9. REST and RESTful Synthesis Copyright © William El Kaim 2016 9
10. 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
11. JSON vs. HTML Compact and easy to process Copyright © William El Kaim 2016 11
12. RESTful Architecture and REST Languages Copyright © William El Kaim 2016 12
13. 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
14. 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
15. 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
16. 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
17. 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
18. SOAP vs. REST Source: PWC REST is leveraging HTTP! Copyright © William El Kaim 2016 18
19. SOAP vs. REST … SOAP is Chatty! Copyright © William El Kaim 2016 19
20. 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
21. API Protocols and Styles Copyright © William El Kaim 2016 21
22. 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
23. 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
24. 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
25. 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
26. 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
27. Level 2 - HTTP Verbs - Example Source: 3Scale Copyright © William El Kaim 2016 27
28. HTTP Status Code Map Source: Restlet Copyright © William El Kaim 2016 28
29. 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
30. 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
31. 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
32. 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
33. 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
34. 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
35. 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
36. Describing your API via Web API Languages Copyright © William El Kaim 2016 36
37. 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
38. 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
39. 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
40. Open API (OAI) version 3.0 Copyright © William El Kaim 2016 40 Source: OpenAPI
41. Swagger Tool (SmartBear) http://swagger.io/ Copyright © William El Kaim 2016 41
42. 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
43. RAML (MuleSoft) http://raml.org/ Copyright © William El Kaim 2016 43
44. 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
45. API Blueprint (Apiary) https://apiblueprint.org/ Copyright © William El Kaim 2016 45
46. Google API Discovery Service https://developers.google.com/discovery/ Copyright © William El Kaim 2016 46
47. JSON API http://jsonapi.org/ Copyright © William El Kaim 2016 47
48. API Transformer https://apitransformer.com/ Copyright © William El Kaim 2016 48
49. High Level Comparison Source: Dzone Copyright © William El Kaim 2016 49
50. Describing Your API With a Tool https://stoplight.io/ Copyright © William El Kaim 2016 50
51. Describing Your API With a Tool https://www.mulesoft.com/platform/api/anypoint-designer Copyright © William El Kaim 2016 51
52. 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
53. 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
54. Example Copyright © William El Kaim 2016 54
55. Copyright © William El Kaim 2016 55
56. Copyright © William El Kaim 2016 56
57. 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
58. 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
59. Register Your API in Public Repository • Apis.io • Api for That • Mashape marketplace • Programmable Web Copyright © William El Kaim 2016 59
60. Create and Grow Your Ecosystem Copyright © William El Kaim 2016 60
61. What’s Needed? Copyright © William El Kaim 2016 61
62. 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
63. Create a Dedicated Dev. Portal https://gelato.io/ Gelato from Mashape (open source) Copyright © William El Kaim 2016 63
64. Create a Dedicated Portal Copyright © William El Kaim 2016 64
65. Make Great Documentation Copyright © William El Kaim 2016 65
66. Provide Code Samples & SDK Copyright © William El Kaim 2016 66
67. Generate SDK Source: APImatic Copyright © William El Kaim 2016 67
68. Provide Easy to Use Tools Copyright © William El Kaim 2016 68
69. Build Your Marketplace Copyright © William El Kaim 2016 69
70. 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
71. 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
72. Organize Meetups http://www.meetup.com/ Copyright © William El Kaim 2016 72
73. 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
74. Participate to Developer Communities https://coderwall.com/ Copyright © William El Kaim 2016 74
75. 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
76. DX Example: DreamFactory https://www.dreamfactory.com/ Copyright © William El Kaim 2016 76
77. 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
78. 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
79. How to Manage API Delivery? Copyright © William El Kaim 2016 79
80. How to Manage API Delivery? Copyright © William El Kaim 2016 80
81. API Management Is Now Required! Copyright © William El Kaim 2016 81
82. 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
83. 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
84. 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
85. 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
86. 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
87. 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
88. 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
89. API Mgt: Capabilities Source: PWC Copyright © William El Kaim 2016 89
90. API Mgt: API Versioning? Copyright © William El Kaim 2016 90
91. 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
92. 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
93. 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
94. 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
95. 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
96. 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
97. API Security: OAuth 2.0 Copyright © William El Kaim 2016 97 Source: SAP
98. API Mgt: API Security? Copyright © William El Kaim 2016 98
99. 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
100. API Mgt: DreamFactory https://www.dreamfactory.com/ Copyright © William El Kaim 2016 100
101. API Mgt Tool Vendors Copyright © William El Kaim 2016 101
102. 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
103. 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
104. 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
105. Adopt a Layered Approach Copyright © William El Kaim 2016 105
106. 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
107. ETSY Example API API API Copyright © William El Kaim 2016 107
108. Five Keys To Great API Copyright © William El Kaim 2016 108
109. 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
110. 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
111. 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
112. Never Forget !!! Copyright © William El Kaim 2016 112
113. 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
114. 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