AWS Summit Barcelona 2015 - Introducing Amazon API Gateway

Editor's Notes

• #4: First understand what has driven the decision to build API Gateway, from customer feedback to wider strategic decisions and market forces Next, look at how the service works, and helps customers with their API services Finally, open it out for Q&A at the end
• #5: Over the past few years the number of APIs published on the internet has grown at an increasing pace AWS customers have been at the epicenter of this, building APIs on our infrastructure offerings AWS itself was one of the first companies to offer APIs for developers to interact with its services, this created the DevOps market Looking at market data from ProgrammableWeb, and talking to our customers, it is apparent that what we see documented on the public internet is only the tip of the iceberg Both startups and corporations are adopting a service oriented architecture and creating internal, hidden APIs to decouple their system architecture.
• #6: At AWS we have some experience building scalable, reliable APIs These are just a few logos but all of our services expose APIs for developers to interact with them In fact, if they wanted to developers wouldn’t have to use the management console at all, and could simply rely on our APIs to automate their workflow
• #7: Just like all other AWS services, we started this process by talking to our customers. This is what they told us Very often APIs are built and deployed quickly, one month down the line customers find themselves looking for a way to version and monitor the APIs, something they had not thought about
• #8: After an API is published, and has become successful, the next challenge facing our customers is how to manage, monitor and monetize the ecosystem of 3rd party developers utilizing their APIs
• #9: Authorization, and auth in general, is a hard task. It’s complex to build and often repetitive work – our customers are reinventing the wheel each time they start a new project.
• #10: Managing traffic and operating a reliable network that can protect endpoints against attack is very hard and requires significant investment in terms of equipment, initial setup, and ongoing operation maintenance.
• #11: Finally, we have an entire new generation of developers adopting AWS. At the forefront of this are mobile developers, who are entirely focused on their end-user experience to succeed in a very competitive market and not interested in building or managing the required, complex infrastructure, and they shouldn’t have to.
• #12: Based on the feedback we received from our customers we worked on a new product, Amazon API Gateway. The ability to create and run multiple version of an API simultaneously. We have also built Stages. These enable developers to deploy multiple stages of each version simultaneously. For example, dev stage, prod stage, or beta stage. API Gateway helps developers create, monitor, and manage API Keys that they can distribute to 3rd party developers Developers who already own an authentication and authorization system can leverage their own infrastructure. For developers who are starting from scratch we have introduced the ability to leverage AWS’ own authorization mechanisms such as Signature V4 on Requests and IAM access policies for fine-grained access control At AWS we already run a very large, reliable network. API Gateway helps developers leverage all the work we have done over the years and allows developers to throttle incoming requests and use CloudWatch to monitor the status and latency of their APIs and set Alarms. Finally, it turns out AWS already had the perfect tool for developers who wanted to build server-less backends, it’s AWS Lambda. With the API Gateway customers can now expose AWS Lambda functions as API endpoints.
• #13: And beyond this, we’ve listened and included additional features such as… Customers will be able to provision and configure a dedicated cache for their APIs, we will serve responses from the cache without hitting a customer’s backend whenever possible Continuing our story on leveraging the powerful network AWS has built, API Gateway leverages Amazon CloudFront to create global distributions for customer’s APIs, this lowers the latency for end users but also gives our customers’ APIs DDoS protection out of the box, both for malicious requests (Layer 7) and for lower level attacks (Layer 3, SYN floods) API Gateway can automatically generate client SDKs based on our customer’s API definition. This allows developers to take their APIs from concept to integration test in a client app in a matter of hours, now weeks Many of our customers use Swagger to define their APIs. API Gateway can import Swagger definitions. We have also built an open source Swagger import tool that our customers can use as part of their development workflow. This way they can keep working with Swagger in their local repository, then import and deploy their APIs into API Gateway at build time We have also integrated with the Apache Velocity templating engine, this allows our customers to transform the shape of requests and responses as they flow through the API Gateway. This gives customers the ability to expose legacy endpoints as modern, RESTful APIs among many other things.
• #15: The first thing we want to look at is the standard flow of an API call, including all components in the system First, a request comes in from a client, this could be a mobile device, a web application or a backend service The requests arrives at one of our CloudFront PoP locations, it’s accepted and routed through to the API Gateway in the customer’s region The API Gateway receives the request, then checks for records in the dedicated cache (if it is configured). If there are no cached records available then it will forward the request to the backend for processing The backend can be a Lambda function, a web service running on Amazon EC2, or any other publicly accessible web service Once the backend has processed the request the API call metrics are logged in Amazon CloudWatch and the content is returned to the client
• #16: Let’s look at what is an API, how you build, and how you deploy an API The first step is to create a new API, and declare its resources and methods. Once an API is declared it can be tested from the Console or the API Gateway APIs, but it is not yet accessible on the internet To make the API available it needs to be deployed to a Stage. Stages help you manage your development, beta, production environments etc. Customers can create as many stages as they want, similar to tagging. Each stage can be configured with its own logging, throttling, monitoring and caching settings At any time you can clone the state of an existing API into a new one, this allows you to start working on v2 of your APIs while v1 is still being developed/fixed. API Gateway saves a history of the last 300 deployments to each stage, at any time you can point a Stage (for example production) to a different deployment
• #17: Let’s look in details at the hierarchical structure of an API The top level element is the API itself, we call it a REST API. A rest API can contain many resources, resources are typed objects that are part of your API’s domain. They also represent the path through which the objects will be accessible You can nest resources, in our example the /pet/{petId} represents an individual pet and is a nested resource of the /pets/ resource. Each resource can declare methods. Methods are the combination of a resource + an HTTP Verb. We support 7 standard HTTP Verbs, For example, a method is the POST to the /pets/{petId} resources – this would be used to create a new pet
• #18: Now that we have declared an API with its resources and methods, we can deploy it to make it accessible to 3rd party developers APIs are deployed to a Stage Stages represent environments, for example development of production In API Gateway Stages are like tags, and developers can create as many stages as they want. A stage is just an alphanumeric string Stages are part of the path that will be used to reach sources and methods, for example the prod stage will be available at execute-api.apigateway.com/stage/resource
• #19: This is a visual representation of how versions and stages are managed by the API Gateway, and how customers can leverage these features for their APIs The first thing we’ll do is declared a V1 API and start configuring its resources and methods The next step is to deploy the API to a development stage, we’ll keep deploying to development as we evolve our API At a certain point, when we are ready for 3rd party developers to access this API, we will publish it to a production stage and distribute API Keys and generated SDKs All along we will keep deploying APIs to both dev and prod including new features and bug fixed Eventually we’ll want to make some breaking changes, and work on a much improved v2 API. However, we cannot make breaking changes to the API in production because we have thousands of developers using it. To manage this situation we’ll simply clone the current state of the v1 API into a new API called v2, and begin development of the new version By cloning we can keep publishing bug fixes to the first release and supporting users that are calling it with a gentle, gradual deprecation “… developers feel like they can deliver what they want, when they want to – and that makes for an extremely valuable tool …”
• #20: Customers can configure the API Gateway to use a custom domain name they provide instead of the standard AWS domain. We expect customers to bring their own signed certificate for the HTTPS endpoints Domain names can be configured to point to an API, our top level item, or directly to a specific stage within an API. Pointing a custom domain name to an API requires the stage to be included in the path If the domain name is pointed directly at a stage there is no need for the path variable, resources can be accessed directly form the API root “/”
• #22: API Keys are a great tool to manage the community of 3rd party developers interacting with the APIs API Gateway allows customers to create API Keys through a console interface or through an API for programmatic creation. Customers can set permissions on API Keys and allow access only to a set of APIs, or stages within an API Calls made by an API Key are logged in CloudWatch so that customers can always track utilization by 3rd party developers
• #23: We always get asked whether API Keys are the authorization mechanism for APIs, so we’ll just be upfront: NO, at least we don’t recommend it We strongly encourage customers to use a temporary tokens based on a successful user authentication, either by leveraging AWS temporary credentials through API Signature Version 4, or their own Oauth mechanism
• #24: AWS gives customers the ability to retrieve temporary, limited privilege credentials that are tied to an IAM role within their AWS account through services like Cognito and STS. Based on these credentials developers can sign calls to the APIs, the generated client SDKs automatically know how to handle these credentials In the next slide we’ll go through a real-world use-case for this Alternatively customers can setup the API Gateway to forward their existing headers to keep using their current OAuth authorization schema
• #25: We’ll go through a use case that leverage AWS Lambda and Amazon Cognito to retrieve temporary credentials for a particular end user and authorize access to the APIs As discussed before the API Gateway helps customers leverage AWS Sigv4 – only one open API is required and then we can verify signatures on all other calls.
• #27: API Gateway uses throttling to help protect customer backends and send only request that they can handle To implement throttling we use the token bucket algorithm Customers can set the number of RPS calls they know their backend can handle, and a rate at which the bucket is refilled
• #28: To limit the number of requests their backend can receive, and further bring down latency customers can configure a dedicated cache for each stage of their API For each method in their APIs customers can configure which parameters between path, query string and headers form the item key in the cache, and assign each item a time to live API Gateway automatically caches responses where configured and avoids calling the customer’s backend if the cached item is available and valid Customers have access to APIs to manage their cache in the API Gateway When a stage is configured with a dedicated cache, and an item is found to be in cache and valid for a request that would otherwise be throttled, the API Gateway will handle the request and return the cached response Customers can pick for a range of possible cache sizes to provision a dedicated cache from their stage, from 0.5GB all the way up to 237GB
• #29: Let’s put the two together and look at the execution path of an API call First, when we receive a request, we will check the dedicated cache (if it’s been configured) If we have an item in the cache then we can handle the request regardless of the throttling configuration, it will have no effect on our customer’s backend Next, if we don’t have a cache, we check the throttling configuration and the current throttling state (our bucket) If we are above the limit we will return a 429 response Otherwise we will execute the backend call and return the result As we mentioned our generated SDKs automatically know how to handle throttling responses, and they will perform an exponential backoff while retrying the call
• #31: API Gateway handles resources as typed objects. Resources can have models associated with them. Models are simply the JSON schema representation of the request and response data models If the API Gateway is aware of the request and response models it can Generate SDKs that include actual objects for each request and response rather than generic (JSON Object) Allow JSON traversal of requests and responses in the data transformation engine
• #32: Let’s look at how request and response data can be transformed in-flight. We use Apache Velocity as the standard to create, save and execute templates We have been working with our customers on this and during development we have seen the following use-cases from them Filter API responses. In many cases legacy APIs tended to return verbose responses with too many objects. Large payloads are a struggle for mobile applications, so customers are using the templates to traverse the response schema and filter the output to return only the necessary fields RPC to REST. Customers have RPC-style APIs that they wanted to expose to the world in the form of RESTful APIs. RPC often only accept POST calls. Customers used the transform templates to accept a GET call in the API Gateway, then generate the POST body for their backend call reading parameters from the path, query string and headers Customers who want to leverage Lambda but only run XML APIs have been using the transform templates to receive the JSON output from Lambda, and turn it into an XML before sending it back to the end user. This has allowed them to completely switch their backend technology while causing no disruption for 3rd party developers utilizing their APIs, very neat tablecloth trick. Example: Twilio
• #33: Example of a simple transformation flow API Gateway + Lambda = Server-less backend Use AWS Lambda to run business logic Use API Gateway to expose the AWS Lambda functions as endpoints Transforms Lambda’s JSON output to XML for their APIs
• #35: API Gateway can generate client SDKs based on a customer’s API definition. Simply select the deployment the SDK should target, the platform, and setup a couple of parameters and the API Gateway generates an SDK and makes it available to download through an API or the management console SDK are model-aware and also come with the built-in AWS core that allows them to handle throttling responses and sign requests using AWS Credentials
• #37: We will create an API that uses as a backend a Lambda function The “Hello World” API will have two methods: GET and POST Each method will be mapped to a different Lambda function When you request the “/helloworld” API the Lambda function will be executed and the function will return the response We are using a very simple node.js function And we will be able to monitor execution of our API trough CloudWatch
• #38: - We created a totally serverless API application in minutes (very simple one).
• #42: Build, Deploy & Manage your APIs Request & Response Transform support Secure access using Sigv4 or OAuth Protect your backend with Throttling & Caching Simplified Client access via SDK Generation Usage-based pricing