It Starts with a Simple REST Client

Abhinav Asthana

October 6, 2016

As many people know, Postman started 4 years ago as a simple client for HTTP requests, spurred by my experience with cURL. The first time I encountered cURL, I did not like it. cURL — for me — was complicated and verbose and hard to understand, particularly for anything beyond simple GET and POST requests. And I needed to go beyond simple GET and POST requests, since real world APIs are complicated! Building an interface and writing code for sending simple requests wasn’t the real challenge – every software language in the world provides ample tools to do that. If you want to work with complex, real world APIs in a simple and effective way, you need a robust tool to support your workflow.

In this blog post, I’m going to walk through how Postman evolved from a simple REST client to a sophisticated, complete API toolchain.

Let’s say you decided today to build your own REST client from scratch. You would start with the basic HTTP methods: GET, PUT, POST and DELETE and build a nice interface for adding and editing. Simple enough, but that’s where things stop being simple.

You’d realize immediately that there are 5 important features that even a simple REST client needs: handling the request body, authorization, cookies, certificates, and result rendering.

Handling the correct request bodies

Turns out, there are different kinds of HTTP request bodies. Some APIs use URL encoding, some APIs accept the standard web form data content type, and some APIs accept full text bodies in JSON and XML. “No problem!” you would say, handling these many cases quickly. However, there are some other APIs that can accept entire files, and you’d build another mode for accepting file inputs. Then you realize it’s not enough: form-data accepts files along with normal text, and each of those files might have different content types.

You decide to start with JSON. Your client would let users add application/json as the default header as a convenience, but since application/json is not the only content type, you’d need to provide options for users, to select the correct default content-type. (Your REST client provides options, because you don’t want to make your users take an extra step in setting the right type.) This leads to a design realization: the choice of the request editor body is tightly tied with the content-type and your editor.

Handling Authorization

Authorization is probably the most important, and also the most frustrating, aspect of getting started with an API. There is limited consensus on the right approach to authorization. So you would get started with Basic Auth, which is simple enough, but then you stumble upon OAuth 1.0. A lot of APIs still use OAuth 1.0! (At this point in the process, you would take a minute to wonder why that is: you’d have hoped that things have settled in the world of authorization types.) The spec is hard to implement, and reference implementations are hard to find. You wade through the OAuth 1.0 docs, and finally get it done.

Which would lead you to OAuth 2.0 – lots of developers use it, and it looks simple enough. Not really! The token needs to be obtained from a server, and OAuth 2.0 servers have multiple flows for obtaining and using request tokens, and now your interface is slightly more complicated. And, you haven’t really even started looking into Digest, NTLM, AWS and Hawk.

Handling cookies

There is an easy way to do auth: cookies. If you were writing a stand-alone client, you’d probably have access to the cookie jar. For a browser based REST client, there are advantages. You don’t need to get people to manage cookies in the REST client, since the browser does it for you. However, at times people do want to manage cookies and have finer control. So you would decide to build a standalone client, which raises another issue. Users will want to share a session with the browser (to authorize themselves against the API), but then also want to change something in the actual cookie.

Certificates

SSL certificates are super useful for API security, and if you were building your REST client in Chrome, Chrome will handle SSL certificates for you. But, there are some complications for the developer – sometimes they will use self-signed SSLs that the browser does not recognize. Your REST client will need to allow users to override the check for self-signed SSLs, if needed. However, there are APIs where having a certificate is an absolute must, otherwise the API won’t return any response data.

Rendering responses

Not all APIs return text: APIs can contain images, PDFs, audio files or any resource you can dream of. Sometimes the client doesn’t even know what the API will return!
Handling a multitude of responses without crashing the client is essential, and will add (absolutely necessary) complexity to your REST client development.

And all this was just the REST client part! Ensuring that the tool that you use for API development behaves correctly in all circumstances has been super important to Postman – the nuances of HTTP requests are complex but necessary in the real world. Building a REST client and keeping it simple is hard.

As Postman has grown, we have expanded beyond my initial tool to help me avoid cURL, into a complete API developer toolchain, always focused on the developer experience. As we did that, we have made two major platform shifts. We moved from our original legacy app to Chrome apps, and more recently, made the shift to native Mac and Windows apps. When we shifted from an in-browser app to the Chrome app platform, we built a bridge called the Interceptor to give developers the best of both worlds. Our native apps provide the same level of control, along with the ease of use of a standalone application.

Along the way, we have rewritten our UI layer in React for great performance, as well as the underlying Postman codebase – Postman Runtime. Runtime allows the developer complete control over HTTP requests, without sacrificing performance in big HTTP operations.

Postman right now is the most complete & advanced cross-platform REST client – as well as so much more. Postman is still simple and easy to use, and the Mac, Windows, and Chrome apps are still free.