When building connected software, upfront planning can save a lot of unnecessary coding. For APIs, planning is especially important. You may not control the consuming software. Even if you do, making API changes can cause a cascade of effort as teams scramble to integrate.
A design-based approach to building APIs can save you—and your API consumers—additional development cycles. Great API design ensures that your API will support the right use cases, provide the right data, and work right from the start.
There are three key elements at the heart of a great API design process: the API schema, collaboration, and testing.
Choose a Schema for Your API Design
Before you design your API, you need a way to communicate what it will include. While this could be accomplished with a list of endpoints or hand-written documentation, that is only so helpful in the design phase. To create a flexible API design that will continue to be helpful as you build your API, you need a schema.
The industry has rallied around OpenAPI, and especially around OpenAPI 3.0. This is one of several schemas supported in Postman 7, which now allows you to create APIs within the app's interface.
You can create and update schemas within the app, or import existing schemas. Postman supports OpenAPI 3.0, in addition to the earlier versions (OpenAPI 2.0 and 1.0) known as Swagger. There is also support for RAML, a modeling language most often used in the API design phase. Finally, you can also bring your GraphQL Schema Definition Language (SDL), which is especially handy for APIs that return a lot of data.
Regardless of the schema you choose, it can be used to represent the API during your design phase. At this point, your API is a concept. You can't make live calls to API endpoints, nor inspect results. However, the schema describes each of these endpoints, how requests are made, and what consumers can expect from responses.
Once your schema is complete, it becomes a descriptive artifact that you can share with others. You can send the schema to the team that will build the API, as well as the team (or multiple teams, such as external partners) that will consume it. Sharing a schema early on in the design process is invaluable for finalizing API functionality. Product teams and other customer-facing teams can review the schema to ensure it isn't missing anything and also supports the uses you've envisioned.
Collaborate Around Your API Design
It's useful to share the schema as-is, but the real opportunity is in what the schema itself can generate. An API schema codifies your design decisions and makes them available in a way machines can understand. Anyone with access to the schema can transform it into a more realistic representation of the API it will become.
In order to collaborate on development, shared development environments can make a huge difference. Postman provides workspaces, but many other development tools provide shared environments as well. When you generate a collection from your schema, you and your team can easily see and manipulate each request while effortlessly maintaining a single source of truth.
Create a workspace for your team to collaborate while you design, mock, build, test, and deploy your API. At each stage, your API schema helps describe the current version of the API.
When you're ready for real feedback on your API design, it's necessary to test each endpoint. You can generate mock servers from your schema. A mock server is a staged version of your API that uses your schema to provide a realistic interface. Typically, the mock server is hosted at a randomized sub-domain using the same paths you've designed for your production API.
Mock servers are especially helpful for split-stack development. Once your design is reflected in an API schema, the team consuming your API can use the mock server to prototype their development. If a request field is invalid (that is, not listed in the schema), they'll see an error. If the response doesn't include a field they expected, you'll find out. It's much easier (and much less costly) to make changes to an API during the design and development phase.
Build and Test Your API
By the time you start building your API, you've already seen benefits from the design-based approach. But, perhaps the greatest value comes when you start to commit code. Your design and collaboration efforts make it much more likely that you won't need to make immediate changes to your API before sending it to production.
The last aspect of a great design approach is to set up a sturdy test suite. Automated testing will catch bugs much more efficiently than manual tests, and you can program tests to run at each build, ensuring that your API is reliable. You can write tests against your API to help ensure the API you build matches the one you designed.
This process is helped by mock servers. Mock servers test your API endpoints, which will likely pass if the APIs generated from your schema. As you build the API, you can deploy it locally or to a staging server. Simply change the _baseUrl_ from your mock server to the staged version of your real API. Run the tests and you'll see how well the API-in-progress performs.
APIs are already allowing for more innovative services with more flexibility and improved capabilities. Great API design can make the difference between inhibiting software or enabling it. A design-based approach encourages API producers to know what they're building before a single piece of code is written. You can visualize expected behavior and catch bugs early so you can build better APIs faster than with other approaches.
To find out how Postman can help you, get started with our mock servers.