GraphQL has emerged as an optimal way to expose databases as a robust API which can support the needs of modern web and mobile applications. Providing an approach to delivering a single API path that provides access to an entire data graph, allowing consumers to define their own queries, and receive exactly the response they need for whatever need they have in their particular application. This is a blueprint to walk through creating a new GraphQL API, while also establishing a well-defined lifecycle around the API, ensuring that it is well documented, tested, and provides a level of service that meets the business objectives of an organization.
GraphQL provides a rich set of solutions for defining the base of an API that will expose the entire surface area of one or many data sources, providing API producers with the ability to define data sources and the resolvers that route API requests to each data source, and the schema that will define how API consumers can craft queries for getting at exactly the data they need. Each of these elements help define the base for a GraphQL API, bypassing the work that is required to design a more RESTful approach to delivering APIs, putting more control into the hands of API consumers. Providing a solid approach to defining access to essential and complex backend data using an increasingly common API pattern.
- Schema - Defining all objects use as part of API operations using JSON Schema provides for a definitions that can be used as part of modeling and the API design process, as well as for validation at development, build, or even run time.
- Data Sources - Providing the sources of where an API retrieves it's data, mapping the API to backend databases that contain the actual resources that will be made available via each API, allowing each API to be able to find data as requests are made by consumers.
- Resolvers - The bindings that map incoming queries to specific data sources so that APIs know where to find resources, distilling down API requests into meaningful queries that will make sense to backend systems, connecting the front end requests to the backend stores, routing API requests to where they need to go.
Having complete, accurate, and easy to follow documentation is essential for all APIs, and is something that alleviates the number one pain point for API consumers when it comes to onboarding with any API, expanding the number of API paths an application puts to work. Modern approaches to producing API documentation have moved beyond a single static version of documentation simply published to a portal, as well as there being potentially multiple forms of documentation for any single API. Helping API producers onboard consumers easier, reduce the cognitive load when understanding what an API does, and properly define specific business use cases of an API being put to work in an application or as part of an integration.
- Reference Documentation - It is helpful for API consumers to have complete documentation for the entire surface area of an API, providing a complete reference of what is possible with an API to help consumers explore every path, parameter, schema, and other details of how an API works, making the resources and capabilities available within API something consumers can find and put to use without much work.
A test-driven API lifecycle ensures that each API delivers the intended outcomes it was developed for in the first place, providing manual as well as automated ways to ensure an API hasn't changed unexpectedly and is as performant as required, helping establish a high quality of service consistently across all APIs. API testing should not be an afterthought and should be a default aspect of the API lifecycle for any API being put into production. API testing takes a solid investment in establishing proper testing practices across teams, but once you do the work to establish a baseline of testing, properly train teams on the process and tooling involved, the investment will pay off down the road.
- Contract Testing - Contract tests can be derived from API artifacts like OpenAPI, JSON Schema, and GraphQL, and used to ensure there are no changes to what has been promised when an API was designed or developed, providing a repeatable test that can be run manually, on a schedule from multiple regions, or as part of a CI/CD pipeline to ensure contracts with consumers are upheld.
- Performance Testing - Performance tests can be defined as individual tests using collections, pulling from one or many individual API paths and measuring the time it takes for the response to be sent, providing a test that can be run manually, scheduled across multiple geographic regions, or executed as part of a CI/CD pipeline, helping ensure an API is always meeting it's expected performance benchmarks.
Security must be its own area of the API lifecycle, but it is something that should span testing, authentication, and potentially other areas of the API lifecycle. Over the last five years the world of API security has expanded, while also moving further left in the API lifecycle as part of a devops shift in how APIs are delivered. There are a number of elements present when it comes to security, but depending on the overall maturity of API operations the available resources and prioritization available to adequately realize these elements vary.
- Authentication - The consistent application of standard authentication as part of a standardized API management layer striking a balance between access to digital resources but ensuring that undesirable actors do not have access to valuable assets.
- Security Testing - Security tests can be defined for any API using executable and shareable collections, testing for common OWASP vulnerabilities, as well as other more custom scenarios or business approaches, providing a single or suite of security tests that can be manually run, schedule across multiple regions, or executed as part of a CI/CD pipeline, automating security consistently across APIs.
Monitors can be used to execute any Postman collection applied to any environment. Due to the versatility of what a Postman collection can define, collections turn monitors into a powerful API automation and orchestration tool. Beginning with the ability to schedule contract, performance, and other types of tests, but then also allowing for automating specific workflows across many different APIs. Since collections can be used to define anything that can be defined via an API, monitors can be used to schedule the running of each capability from multiple cloud regions, applying many different environmental variables. Making monitors an essential, versatile, and executable part of defining how the API lifecycle works.
- Contract Testing Monitor - Monitors can be setup for all API contract testing, scheduling the run of contract testing when needed and configuring to run from the regions that matter most to business operations, making sure that each individual API contract is never breaking with consumers, making sure that each API is delivering as expected on a 24/7 schedule.
- Performance Testing Monitor - Monitors can be setup for all API performance testing, scheduling the run of performance testing when needed and configuring to run from the regions where performance makes the most difference on business, making sure that each individual API SLA is met, identifying API performance issues early on and responding to ensure there is no significant business impact.
The ability to discover APIs at all stages of the API lifecycle is essential for reducing redundancy across operations, helping teams find existing APIs before they develop new ones, properly matching API consumers with the right APIs, while supporting documentation, relevant workflows, and the feedback loops that exist as part of the operation of APIs internally within the enterprise, or externally with 3rd party developers. API discovery does not live at the beginning or the end of the API lifecycle, but should be considered across all areas of the API lifecycle, ensuring that APIs, as well as the operations around them are as discoverable as possible, but well informed when it comes to privacy, security, and terms of service.
- Search - Ensuring APIs are always available via search helps make sure that APIs can be found by consumers, but also by other producers who are looking to develop similar APIs, making search for APIs, as well as the operations around each API a critical aspect of the API lifecycle that should be considered as early on in the design and development of an API, but at least as it is deployed into production.
- Private Network - Private API networks all organizations, groups, and teams to establish private catalogs of APIs, collections, and the other artifacts and elements around them, making it easier for producers and consumers to find APIs that are being designed, developed, or operating in production, making APIs more accessible but only to an intended audience.
- Public Network - Public API networks allow for teams, APIs, collections, and other elements to be made available for searching and browsing by a public audience, helping API producers reach a larger audience, but also allowing consumers to quickly find the APIs and other resources they need in their applications and integrations, networking consumers with producers in an ongoing and collaborative way.