Upgrade to Pro — share decks privately, control downloads, hide ads and more …

APIs Design, Creation and Management

APIs Design, Creation and Management

APIs Design, Creation and Management

william el kaim

December 11, 2016
Tweet

More Decks by william el kaim

Other Decks in Technology

Transcript

  1. This Presentation is part of the Enterprise Architecture Digital Codex

    http://www.eacodex.com/ Copyright © William El Kaim 2016 2
  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 Copyright © William El Kaim 2016 3
  3. 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
  4. 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
  5. 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
  6. 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
  7. 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
  8. 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
  9. 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
  10. 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
  11. 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
  12. 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
  13. 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
  14. 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
  15. 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
  16. 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
  17. 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
  18. 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
  19. 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
  20. 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
  21. 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
  22. 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
  23. 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
  24. 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
  25. 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
  26. 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
  27. 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
  28. 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
  29. 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
  30. 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
  31. 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
  32. 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
  33. 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
  34. 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
  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 58
  36. Register Your API in Public Repository • Apis.io • Api

    for That • Mashape marketplace • Programmable Web Copyright © William El Kaim 2016 59
  37. 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
  38. 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
  39. 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
  40. 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
  41. 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
  42. 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
  43. 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
  44. 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
  45. 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
  46. 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
  47. 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
  48. 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
  49. 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
  50. 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
  51. 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
  52. 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
  53. 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
  54. 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
  55. 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
  56. 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
  57. 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
  58. 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
  59. 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
  60. 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
  61. 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
  62. 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
  63. 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
  64. 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
  65. 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