Building a Public Facing API

Many startups need to expose their services to developers as a public API. They might do so for monetization, visibility, and engagement that results in growth. As developers, you need to address a wide range of requirements when building an API. There are also many ways to build APIs. Prioritizing the important requirements and selecting the right implementation options can be challenging. In this article, we cover the important elements of building a public API and how you can do so on AWS. Before developing a public API, you need to consider a few important factors to make sure the public API is simple, secure, and scalable.

Key Factors in API Development

First, users of public APIs are usually developers, so it is important to build APIs that are simple and intuitive for them. Developers usually adopt API standards that have necessary tools, frameworks, documentation, and community support. REST and GraphQL are popular standards for building APIs.

Second, as public APIs are the main interface point between clients and backend services, their throughput depends on factors like number of users and activity in frontends. Consequently, APIs need to scale from handling a few requests to millions within a short period of time.

Third, public APIs usually expose backend data to customers or clients that have access, so they need to be secure, hence the importance of authentication and authorization of users. As API usage involves transfer of data between clients and servers, encryption during transit is also critical.

Fourth, because organizations expose the same public API to many customers simultaneously, they need to focus on features that enable multi-tenant design, making sure that a single organization’s usage of the API does not impact others.

Finally, when a startup adds more features and functionality to its products, APIs tend to change, and new versions are released at a fast pace. Public API developers need to consider hosting multiple versions of APIs simultaneously to ensure a smooth migration of clients from older to newer versions.

REST vs. GraphQL?

Next, we explore the various integration options for exposing public APIs to end users. Developers building modern applications expose their public APIs using REST and/or GraphQL.

REST, or Representational State Transfer, is a software architectural style that defines a set of constraints to be used for creating web services over HTTP for retrieving data (also called resources). GraphQL is an open-source data query and manipulation language for APIs and a runtime for fulfilling queries with existing data. To decide whether you need to expose your public API as REST or GraphQL, consider your end users’ technology preferences for data fetching, error handling, and caching.

REST is based on well-known HTTP methods like GET, POST, PUT, and DELETE that map to Create, Read, Update and Delete operations. GraphQL data fetching is based on a set of queries and schemas defined by the developer to expose relevant data.

In a typical REST API, to fetch or retrieve data from a server, we end up making requests to multiple endpoints. But with GraphQL, we only have one endpoint with which we access data on a server. With a single request, we can get an object and its related objects.

While REST APIs can provide multiple error codes, it is always Response code 200 in case of a GraphQL API. The response body contains the error with details.

Since HTTP protocol already implements caching, and REST is implemented using HTTP, the client can use HTTP caching to avoid refetching resources. GraphQL has no caching mechanism in place, leaving the clients with the responsibility of taking care of caching on their end.

You also need to consider the fact that a GraphQL API requires a clear definition of schemas and implementation of reads, writes, and updates, also known as queries and mutations, for backend integration. Conversely, a REST API does not impose any strict standards on integration. While each option has its pros and cons, the two are not mutually exclusive. It is possible to expose a service with both REST and GraphQL APIs at the same time.

How to Build a Public API

Now that we have reviewed integration options, we go into how to build them on AWS. For developers on AWS, solutions for building public APIs fall into two categories: fully managed or built.

You can use a fully managed service such as Amazon API Gateway for REST APIs or AWS AppSync for GraphQL APIs. These managed services are built based on our experience working with thousands of startups. They incorporate the most frequently requested features and are a great option since you can build simple, secure, and scalable APIs with minimal effort.

Alternatively, you can build the API interface on your own using various AWS components such as Compute and Load Balancers as building blocks to host the service. There are also several open-source, language-specific frameworks that you can host on AWS using those building blocks. Choosing to build or host an open source framework provides higher flexibility and control but comes with the operational burden of managing the infrastructure by yourself.

At AWS, we encourage our customers to avoid undifferentiated heavy lifting in their journey, so we recommend using a fully managed service for building an API.

For building REST-based APIs, we recommend API Gateway, a fully managed service that makes it easy for developers to create, publish, maintain, monitor, and secure APIs at any scale. API Gateway handles all the tasks involved in accepting and processing up to hundreds of thousands of concurrent API calls, including traffic management, authorization and access control, throttling, monitoring, and API version management.

API Gateway enables developers to build multi-tenant systems by providing features like request throttling, monitoring, logging, and tracing. For simplifying REST API integration, the API Gateway can generate client SDKs for a number of platforms to quickly test new APIs from your applications and distribute to third-party developers. 

For building GraphQL based APIs, we recommend AppSync, which is a managed service that uses GraphQL to make it easy for applications to get exactly the data they need. With AppSync, you can build scalable applications, including those requiring real-time updates, on a range of data sources such as NoSQL data stores, relational databases, HTTP APIs, and your custom data sources with AWS Lambda. For mobile and web apps, AppSync additionally provides local data access when devices go offline, and data synchronization when they are back online.

Both API Gateway and AppSync enhance developer experience by making integration easy with backend services. Both services scale from a few users to millions without requiring the developers to make code or configuration changes. Security services like AWS IAM and Amazon Cognito are seamlessly integrated into these services. 

Conclusion

Startups need the ability to quickly build simple, secure, and scalable public APIs with minimal effort. API Gateway and AppSync provide serverless platforms that allow you to focus on building your customers' experiences without worrying about factors like hosting, scaling, high availability, security, and performance. These services give you the choice of building REST APIs and/or GraphQL APIs. Features like the ability to generate SDKs in multiple programming languages provide your customers with a great developer experience.

Now that you have a better understanding of the elements to consider and the options available to build a public API on AWS, the next step is to build your first API by exploring our API gateway developer portal and AppSync SDK.

Have fun, and build on!