Introduction to Amazon API Gateway
SPL-58 - Version 2.0.9
© 2018 Amazon Web Services, Inc. and its affiliates. All rights reserved. This work may not be reproduced or redistributed, in whole or in part, without prior written permission from Amazon Web Services, Inc. Commercial copying, lending, or selling is prohibited.
Errors or corrections? Email us at firstname.lastname@example.org.
Other questions? Contact us at https://aws.amazon.com/contact-us/aws-training/
In this lab, you will create a simple FAQ micro-service. The micro-service will return a JSON object containing a random question and answer pair using an Amazon API Gateway endpoint that invokes an AWS Lambda function. Here is the architecture pattern for the micro-service:
By the end of this lab you will be able to:
- Create an AWS Lambda function
- Create an Amazon API Gateway endpoints
- Debug API Gateway and Lambda with Amazon CloudWatch
Some programming experience and familiarity with application development will be helpful, but not necessary to run the lab. You should however have completed the Introduction to AWS Lambda self-paced lab before this doing lab.
Other AWS Services
Other AWS Services than the ones needed for this lab are disabled by IAM policy during your access time in this lab. In addition, the capabilities of the services used in this lab are limited to what is required by the lab and in some cases are even further limited as an intentional aspect of the lab design. Expect errors when accessing other services or performing actions beyond those provided in this lab guide.
"The microservice architectural style is an approach to developing a single application as a suite of small services, each running in its own process and communicating with lightweight mechanisms, often an HTTP resource API. These services are built around business capabilities and independently deployable by fully automated deployment machinery. There is a bare minimum of centralized management of these services, which may be written in different programming languages and use different data storage technologies." -- James Lewis and Martin Fowler
The idea of a microservices architecture is to take a large, complex system and break it down into independent, decoupled services that are easy to manage and extend. This enables developers to meet their key design goals like extensibility, availability and maintainability.
Amazon API Gateway and AWS Lambda provide the perfect combination of web services to effortlessly build, deliver and maintain a suite of microservices that can be the foundation of complex software systems.
In this lab, you will learn how to develop, deploy and debug a simple microservice that represents one part of a much larger system. It will consist of two pieces: the RESTful API and the function that is executed when a user hits the endpoint.
Application Programming Interface (API)
An application programming interface is a set of instructions that defines how developers interface with an application. The idea behind an API is to create a standardized approach to interfacing the various services provided by an application. An API is designed to be used with a Software Development Kit (SDKs), which is a collection of tools that allows developers to easily create downstream applications based on the API.
Many software organizations are adopting an API-First strategy, where each service within their stack is first and always released as an API. When designing a service, it is hard to know all of the various applications that may want to utilize the service. For instance, the FAQ service in this lab would be ideal to seed FAQ pages on an external website. However, it is feasible to think that a cloud education company would also want to ingest the FAQ within their training materials for flash cards or training documents. If it was simply a static website, the ingestion process for the education company would be very difficult. By providing an API that can be consumed in a standardized format, the microservice is enabling the development of an ecosystem around the service, and use-cases that were not initially considered.
Representational state transfer (REST) refers to architectures that follow six constraints:
- Separation of concerns via a client-server model.
- State is stored entirely on the client and the communication between the client and server is stateless.
- The client will cache data to improve network efficiency.
- There is a uniform interface (in the form of an API) between the server and client.
- As complexity is added into the system, layers are introduced. There may be multiple layers of RESTful components.
- Follows a code-on-demand pattern, where code can be downloaded on the fly (in our case implemented in Lambda) and changed without having to update clients.
This lab is following a RESTful model. Clients send requests to backend Lambda functions (server). The logic of service is encapsulated within the Lambda function and it is providing a uniform interface for clients to use.
Best Practices for Building a RESTful API
A key goal of building an API is to help establish an ecosystem of innovation around your set of services. Therefore, it is important to make your API intuitive and easy-to-use. Here is a common naming and method scheme to follow:
|GET||/questions||Returns all of the questions|
|GET||/questions/17||Returns the question number 17|
|POST||/questions||Creates a new question|
|PUT||/questions/17||Updates question number 17|
|PATCH||/questions/17||Partially updates question number 17|
|DELETE||/questions/17||Deletes question number 17|
Notice how to get a specific question, the API endpoint is NOT /question/name but instead /questions/identifier. This enables the API designer to provide functionality to return groups of questions (could be all questions) with the /questions endpoint as well as single record responses with the /questions/identifier. For more information, see the additional resources section at the end of this lab guide.
A few good examples of RESTful APIs to look at are:
Amazon API Gateway and AWS Lambda
A microservice using Amazon API Gateway consists of a defined resource and associated methods (GET, POST, PUT, etc.) in API Gateway as well as the backend target. In this lab, the backend target will be a Lambda function. However, the backend target could be another HTTP endpoint (a third-party API or listening web server), an AWS service proxy or a mock integration to be used as a placeholder.
Amazon API Gateway
API Gateway is a managed service provided by AWS that makes creating, deploying and maintaining APIs easy. API Gateway includes features to:
- Transform the body and headers of incoming API requests to match backend systems
- Transform the body and headers of the outgoing API responses to match API requirements
- Control API access via Amazon Identity and Access Management
- Create and apply API keys for third-party development
- Enable Amazon CloudWatch integration for API monitoring
- Cache API responses via Amazon CloudFront for faster response times
- Deploy an API to multiple stages, allowing easy differentiation between development, test, production as well as versioning
- Connect custom domains to an API
- Define models to help standardize your API request and response transformations
Amazon API Gateway and AWS Lambda Terminology
- Resource: Represented as a URL endpoint and path. For example, api.mysite.com/questions. You can associate HTTP methods with resources and define different backend targets for each method. In a microservices architecture, a resource would represent a single microservice within your system.
- Method: In API Gateway, a method is identified by the combination of a resource path and an HTTP verb, such as GET, POST, and DELETE.
- Method Request: The method request settings in API gateway store the methods authorization settings and define the URL Query String parameters and HTTP Request Headers that are received from the client.
- Integration Request: The integration request settings define the backend target used with the method. It is also where you can define mapping templates, to transform the incoming request to match what the backend target is expecting.
- Integration Response: The integration response settings is where the mappings are defined between the response from the backend target and the method response in API Gateway. You can also transform the data that is returned from your backend target to fit what your end users and applications are expecting.
- Method Response: The method response settings define the method response types, their headers and content types.
- Stage: In API Gateway, a stage defines the path through which an API deployment is accessible. This is commonly used to deviate between versions, as well as development vs production endpoints, etc.
- Blueprint: A Lambda blueprint is an example lambda function that can be used as a base to build out new Lambda functions.
Join Qwiklabs to read the rest of this lab...and more!
- Get temporary access to the Amazon Web Services Console.
- Over 200 labs from beginner to advanced levels.
- Bite-sized so you can learn at your own pace.