How do you explain how your API works?

Maintaining specification for API is a useful thing. It makes onboarding easier for new developers in the company, for testers, for security specialists and finally to 3rd party developers who want to use your API.

Sometimes, those reasons are not enough and writing the specification ends up at the bottom of your todo list, specially for internal APIs. But even for those there are advantages to having a spec, such as client and server code generation, security testing and others.

However, specifications are only one of the many ways developers store information about APIs. Let’s take a look at the most popular ones.

API Specification

API specification is a way of documenting API so it is easily understood by software. A good example is WSDL, language that helps to describe WebServices. Other good examples are WADL (extension of WSDL), RAML or Open API Spec (formerly known as Swagger). They enable automation in many areas:

• Client & server code generation
• Validation
• Static documentation generation
• Automated security testing (Rest Secured)

Below you can see documentation generated based on Open API specification.

Swagger UI

Static documentation

Most static documentation formats are created from Markdown with some extensions. A great example is Slate. With few extensions for languages, one markdown file is transformed into a beautiful website.

Slate

Postman

Postman is a tool suite that requires a separate section in this blog entry! I’ve started using Postman when was it a Chrome plugin that enabled saving sample payloads into collections.

The user now can import collections from curl commands, import Swagger spec or intercept calls directly from browser. Later on invoking HTTP calls can be automated using Newman.

Clipboard FTW!

I’m curious what percentage of developer’s have a huge notepad document with lot’s of example payloads, curl commands, sample responses etc. I have and I’m not alone.

It’s great knowledge place that doesn’t fit documentation or rapidly evolves during development and ctrl-c and ctrl-v are probably the most worn out keys.

Having such a stash of snippets is not bad, but it’s difficult to share or use.

Documentation maturity

At Rest Secured we want to support every kind of knowledge to properly do the security assessment of your API. We support API specifications and now we’ve started supporting sample snippets with the CLI tool called Rest Secured Copilot.

Maturity

If you are registered to Rest Secured — To start using Copilot just type commands:

/> brew tap restsecured/tap && brew install restsecured-copilot
/> rsc authorize  <token generated on Rest Secured profile page>  https://www.restsecured.xyz
/> rsc scan

You will be asked for sample URL, sample payload and that’s it. After few minutes you will receive report link you can review online. That way you can test API developed locally on your PC — it’s still alpha version, but give it a try!

If you would like more about posts like this please follow me and our blog and let us know what you think on the comments!