Creating a New GraphQL API

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.

Define

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

In the world of APIs schema define almost every aspect of our operations, providing us with a framework for how something is structured, but because schema are machine readable, it also provides us with how something will work, and with linting and validation also whether something is working as defined by a specific contract. Schema is most often associated with data made available via APIs from databases, but schema also is used to define every stop along the API lifecycle, and provides us with the artifacts we need to properly govern the API lifecycle. Schema is how we define shared meaning across our API operations, between teams moving APIs forward, but also with the consumers who are putting the digital resources, capabilities, media, and algorithms we make available via our APIs to work in their applications and integrations. There are numerous opportunities for defining, managing, and putting schema to work across the Postman API platform when it comes to producing or consuming APIs.

Data Sources

APIs provide managed programmatic access to potentially a variety of data sources, with a variety of gateway solutions for connecting, resolving, applying business logic, and transforming data from data sources as it is being made available via APIs. While it is common for API developers to directly expose data sources as create, read, update, and delete (CRUD) APIs, it is much more desirable to expose data sources as well designed API paths, as well as via GraphQL and other query languages. Data sources and APIs have a natural relationship as part of the development and delivery of APIs, but there are a variety of approaches you can take to connect data sources via your APIs.

Resolvers

Resolver is a collection of functions that generate response for a GraphQL query. In simple terms, a resolver acts as a GraphQL query handler. Every resolver function in a GraphQL schema accepts four positional arguments. A resolver is a function that’s responsible for populating the data for a single field in your schema. It can populate that data in any way you define, such as by fetching data from a back-end database or a third-party API. Providing the essential mapping needed to handle the requests coming in via a GraphQL, make the round trip to some backend system to retrieve the data, and then return the data in the desired format as defined by the API consumers query.

Document

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

The most common form of API documentation is what can be described as reference documentation, providing a complete “menu” of all paths available for an API, along with all the parameters, headers, body, and examples to put to use. Ideally reference documentation is logically organized using folders and tags, and provides informative and useful summaries and descriptions for every individual path. Every API should have up to date and informative reference documentation that allows API consumers to understand the entire scope of an API, but also find exactly the path or paths they need to use as part of their application or integration. Reference documentation for all APIs is an essential part of a healthy API lifecycle, but teams should also be considering what other forms of documentation would help new users, specific domains, as well as describing some of the most common workflows an API is used for when it comes to desired business outcomes.

Test

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 testing ensures that each individual API and collection paths comply with the contract that was put forth for each individual version of an API. OpenAPI for each API can be used to generate collections providing 100% coverage for all of the API paths present. JSON Schema provides the details of the contract, and when applied as part of an OpenAPI definition, you end up with a machine readable contract that can be manually or automatically tested against. It is common for collections to be defined for the contract tests of each API, and then have these contracts tests scheduled for regular run via a monitor, as well as included as part of CI/CD pipelines, providing robust coverage for contract tests that developers can manually execute, or automated as required as part of the API lifecycle.

Performance Testing

Performance testing establishes a benchmark for what can be expected when it comes to the response time for each API. The OpenAPI for each API can be used to generate collections that provide 100% coverage for all of the API paths present, or performance tests can be applied to just a subset of API paths. It makes sense to have performance test collections separate from other types of testing so that they can be run independently from contract, integration, or other types of tests. Helping establish that the performance levels are met from potentially different regions that reflect actual application usage of APIs. Providing a comprehensive look at the performance of an API from across multiple regions for 100%, or a sensible sampling of API paths, ensuring that APIs and the teams behind them are meeting their SLAs over time and across the entire API lifecycle.

Secure

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

Authentication begins on the producer side by selecting the appropriate authentication method when deploying an API to the gateway, setting the tone for how identity, authentication, and access control will work across the API lifecycle. Next, authentication can be defined as part of API consumption at the collection, folder, or individual request level, providing a configurable authentication layer for automating across API operations. Authentication should be balanced across both the producer and consumer side of the API lifecycle, putting well-known practices to work, allowing both sides to securely access, refresh, and engage with necessary authentication.

Security Testing

Security testing ensures that 100% of the surface area of an API is secure against the common types of attacks as defined by OWASP. The OpenAPI for each API can be used to generate collections that provide 100% test coverage for all API paths, ensuring that every API, and detail of the API is evaluated as part of common security practices. No API should move into production without having a security collection defined for testing for all of the known vulnerabilities, moving the security conversation further left in the API lifecycle–allowing developers to manually test as they develop an API, but then also allowing for the automation of API security testing as part of the deployment pipeline, or scheduled via a monitor. Security testing is just one part of a larger testing, but also security strategy, helping standardize how security is applied, while also properly equipping teams with the latest information and practices they need to be successful in securing API operations.

Monitor

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 used to automate the scheduling of any contract test, taking any collection of API requests, complete with test scripts, combined with a targeted environment, and run in a variety of cloud regions on a recurring schedule. Providing the ability to independently execute the contract testing for each API, but then monitor the contract testing of each API over time to make sure nothing has changed. Providing the essential automation of contract testing needed to ensure it is consistently applied across all APIs, defining whether or not an API is not just meeting the uptime portion of its service level agreement, but actually is meeting business needs in an ongoing way.

Performance Testing Monitor

Monitors can be used to automate the scheduling of any performance test, taking a single, or a variety of API paths and making sure they meet the established baseline for response time. Monitors take your performance testing collections and allow for their execution on a recurring schedule, from any cloud region, with a specific set of environment variables applied at execution time. It is important that performance testing exist as their own collections so that performance testing monitors can become more precise in where and when they run, providing a robust look at API performance from the regions and times of day that matter the most. Performance testing monitors are essential in realizing a certain quality of service at scale across all APIs in production, providing an executable unit for understanding the performance of all API resources and capabilities over time.

Discover

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

Search is the fundamental element of API discovery, allowing API producers to search for existing APIs before they begin the development of new APIs, as well as API consumers to search for APIs they can use as part of their applications and integrations. A healthy API lifecycle depends on the ability to search internally and externally for APIs, as well as the operations around them. The indexing of workspaces, APIs, and the elements of the API lifecycle like documentation, mock servers, and tests should occur by default across all teams before the desired efficiency and velocity will be realized across operations. Postman platform search provides visibility across these dimensions of API operations, looking across private, partner, and public dimensions, but then also leverages a role based approach to what elements of API operations are surfaced based upon your role–making API search a priority as part of the API lifecycle.

Private Network

A private network is available for any team as part of the Postman platform. The private team network is accessible via the home page and provides a place to publish APIs, and each version of an API so they can be discovered by internal consumers. APIs can be added to the private network from the network itself, as well as part of managing the API within any workspace where the API is being managed. APIs in the private network will show up in the wider search, and allow for grouping and browsing by folder. Enabling teams who are producing APIs to easily increase the visibility of their APIs across teams, and beyond the workspaces where they are being developed. Increasing the chance that other teams will find before they begin developing a potentially duplicate API, or be able to put it to use within the application or integration they have planned.

Public Network

The Postman public network is where you will find APIs from leading providers like Stripe, Twilio, and Salesforce, while also being the place you can publish your own public APIs for discovery by millions of Postman users. The public network is where teams can discover other public APIs they can put to work, or help make their own public APIs more discoverable by other 3rd party consumers. APIs can be published to the public network by changing the visibility of the workspaces they are in to be public, making the APIs, collections, environments, and other elements viewable by anyone browsing or searching the Postman public API network. The public network isn’t just about API discovery, it is also about helping bring observability and engagement with public API consumers more discoverable and accessible. Moving from the many siloed API portals of the past, where API producers work to build their own API ecosystems, to where API producers just participate as part of a larger API platform ecosystem–where developers already exist.

Conclusion