How to Create Better APIs with Automation

You might think APIs and automation are almost synonymous. It’s true that when using an API, you’re building software to automate something.  However, while engineers build APIs to enable automation, they don’t always get the same benefits themselves during API development. Building APIs is often a manual process prone to costly errors. Though APIs are no longer new (ProgrammableWeb is going on 15 years!), the toolset inside the enterprises that build APIs is still rapidly evolving. 

API schemas can support more automated processes that safeguard development and ensure that the original API design is carried out. You can create a CI/CD pipeline, generate documentation, run mock servers, and create tests with schemas.

I’ll address the common problems with API development below and show how automation can help enterprises create better, faster, and more reliable APIs.

An API Schema Keeps Everyone on the Same Page

You likely have multiple people involved in designing, building, and using your APIs. In a design-based approach to API development, you want your team involved from the start. For this, you need to be able to communicate about the API using a schema, a defined format to represent your API.  Among the potential formats are OpenAPI 3.0 (previously called Swagger), RAML, and GraphQL’s Schema Definition Language (SDL).

The advantage of a schema is that you can develop the API architecture via an outline or model that will become a descriptive artifact that you can share with other members of your team in order to collaborate.  With a shared description of an API, you can envision, describe, or establish your API endpoints before you ever start writing a line of code.

A great way for enterprise teams to collaborate with that schema is with Team Workspaces in Postman.  Very briefly, workspaces are an excellent tool for collaboration on API development because they guarantee every team member is working on the most recent version automatically, all while maintaining permissions through set roles.  
When working within a team workspace, updates to your collection or API are automatically shared to everyone in that workspace. This allows everyone to easily stay up-to-date on project changes and who made them. Everything is tracked with Postman’s built-in activity feed.

Sharing design and development from the beginning offers teams an advantage in enabling each member of the team to be on the exact same page so you can get your API right the first time with no wasted code.

Test Against Your Schema

In addition to a  schema giving you and your team a map of your API design, it provides a framework that you can test against in order to ensure that you and your team are on the right track during development and at each iteration of your API. When an API is built differently than described, it can cause problems in the software that depends on your API - even total breakage. 

As you begin to build out your endpoints, creating a test suite that can be repeatedly run can save costly development time. There are several tools that allow this functionality, including Postman. 

You can write a slew of tests in Postman with JavaScript and automate these tests with the Collection Runner. This allows you to test each endpoint throughout development - ensuring you catch and fix bugs right away. 

Mock servers are another valuable tool during development, so you can see exactly how your API will run even before it’s in production. Mock servers simplify API design and planning, support split-stack development, and help you ensure that your API will run the way it's supposed to once deployed. Postman provides a simple way to create tests and examine your API endpoints with mock servers. 

Postman’s goal is to help make automation as easy as possible so that your team can build entire integration test suites as quickly and thoroughly as possible.  

Monitor Your Live and Development Servers for Errors

By the time you begin to monitor your actual API code, the benefits creating a CI/CD pipeline against your API schema should be clear.  By now, your whole team has vetted the API and, likely, many errors were caught and repaired before any code was committed. With your API up on development servers, you can use the same tests that you and your team wrote to sanity check the API to ensure it works as expected. 

If you want to know more about monitoring, this section of the Postman documentation may be helpful.

Automate Better APIs

An enterprise organization needs solutions that are flexible, team-oriented, transparent, and efficient. Teams work faster because schemas help a team visualize API behavior, which helps teams give each other feedback and resolve a great deal more issues during development.

There’s plenty about building APIs that can’t be automated - but automating the pieces of development that you can greatly speed up time to production and the quality of your API. When you understand the problems you’re solving and how an API will be used, you can codify the choices your team makes and use that to get feedback from your API consumers - allowing you to fill gaps in functionality and expand on your test suite with new information about how your API functions with other services. 

For more information on how automation can help you build, deploy, and run the best API possible, read our whitepaper on automated testing.

Be sure to read the next API Design article: Stoplight Announces API Visual Editor

 

Comments (0)