The API First Strategy
At Polder Knowledge, we often apply an “API First Strategy”. There is some debate on what API First actually means, but at Polder Knowledge we interpret this as a loose project that contains the business logic for an application. This business logic can be used by talking to REST and RPC API’s. The benefit of building a separate API is that it becomes easier to separate different concerns. Because of the existence of this API, we are able to build applications for web, mobile and tablets en to build websites that talk to the same API and thus, share logic. Result? Mobile developers can focus entirely on their app, front-end developers can focus entirely on their website and back-end developers can focus solely on the API itself. We moved the logic to the API, instead of managing it in applications.
To develop API’s, our primary weapon of choice is Apigility. Apigility comes with a big chain of tools that makes it possible to build stable, professional API’s. The tool supports OAuth 2.0, JSON Hypertext Application Language (HAL) and Problem Details for HTTP APIs, which makes it possible to have lot of work being done for us. This makes it possible for us to focus entirely on the business logic of the application.
Developing API’s while applying the API First Strategy does not mean that the API has to be finished before the mobile app or website can be built; these are often developed simultaneously. This means that the developers of the API need a way to run and test their HTTP calls. Luckily, there is an awesome tool that is able to do that for us: Postman
Development using Postman
Postman lets you organize your HTTP calls; it will allow you to configure all available API calls, so you can save them and re-use them. It is also possible to share your collection of API calls with your colleagues. I will present you some tips that have been very useful for the Polder Knowledge team during development. These tips might sound obvious to some and they might help others. Hopefully they can help you!
Organization and Categorization
A common application might contain dozens of API’s. REST API’s are commonly setup with a service you can apply actions on (the HTTP verbs). For example: to create a new entity, you would commonly execute a POST request to the endpoint for that entity. We have learned that it helps to organize these endpoints with the collections that Postman offers. In the screenshot below, you can see that we created a collection called Evolve. This collection contains a number of endpoints which we have categorized in their own folder.
Naming Convention
By prefixing the API call with REST or RPC, it becomes clear what kind of call is made. We differentiate REST and RPC from each other by prefixing the call with the type. Next it is helpful to make it clear whether or not you are executing the request on the collection or on the entity itself.
View Modes
We are all human, so mistakes will be made, right? When testing your API calls, it often happens that you expect JSON, but a server error occurs. When an application does not handle the Accept header correctly, HTML errors will be rendered. Postman allows you to switch between rendered views and raw views. This is extremely useful in cases where server errors occur, as it makes you able to read the data in a rendered way. Postman will also parse JSON and XML, so that your data becomes easier to read.
Authorization
When your API makes use of authorization, Postman will allow you to setup authorization for your API calls. Easily get OAuth access tokens, use Basic Authorization or Digest Authorization.
Sharing
Once your API calls are nicely organized, you are able to share them. You can either share the API via the Postman cloud or you can easily export the API to a JSON. These JSON files can be committed to a repository or you can share them with your teammates.
Variables and Environments
Imagine you have a local web server that you are able to reach via the domain webserver01.host. Your colleague also has a local web server which can be reached via myproject.host. Once you setup your API calls, you enter your own web server URL. Now you export your API to a JSON file and your colleague imports it again. Your colleague will see all your local URL’s which is, as you can imagine, not ideal. This can simply be fixed by using variables. Variables can be used in each field that can be populated within Postman.
Postman makes use of environments, that help you change the set of variables per project you work on.
Once your environment is created and you have added variables, you can use them where ever you like. Postman even gives you autocompletion!
Testing
So, now you’ve got your API all structured and organized, you are even able to share your API with teammates. But, how awesome would it be if you could make sure the API response is valid? Well, Postman offers you this possibility!
Make sure you take a look at Newman as well, as it offers the possibility to run your Postman tests on the command line. This means you can hook this up in your Continues Integration build chain.
To summarize…
Postman offers a great set of tools to optimize your development flow. Organizing, collaboration and testing all is possible with Postman. I hope these tips helped you to optimize your development flow. Make sure to reach out to us via Twitter (@Polder Knowledge) if you have any other tips!