Wednesday, June 20, 2018

#634 API Design with Apiary

As you probably know, Oracle acquired Apiary quite some time ago.
It complements our API Management story, allowing us to provide full API lifecycle support.

So what do API designers get with Apiary?

A plethora of docs is available here

Essentially Apiary gives me an Editor that allows me to define and document my APIs.

It also includes a Mock Server, that allows me to run that API, based on my  definition.
I can then give the Mock Server endpoint to my mobile developer, Annie, allowing her to create our compelling mobile app. In the meantime, I can give my service developer, Pat, access to the API definition. He then implements the API. Apiary allows me to sync with GitHub, so I put my API definition there. Pat also uses the same GitHub repository to store the API implementation. 

From within Apiary, we can then use -

Dredd reads your API description and step by step validates whether your API implementation replies with responses as they are described in the documentation.

We then come full circle when we connect our API Definition in API Platform Cloud Service to Apiary.

Now back to API design with Apiary -

I begin by creating a new project -

Team means others can view/edit the API as required. A team administrator is responsible for setting up teams etc.

Within Apiary itself you have a personal view and a team view.

I go to my newly created API

Left panel - API Blueprint definition

Right panel - Documentation Preview

Updates to the definition are automatically reflected in the preview.

The API is pre-seeded with a dummy "Polls" api definition.
I can amend this to suit my needs -

The preview - 

I click on Create a New Order -

Now I can take the url and test via Postman -

The very same url I can pass on to my mobile developer, Annie.
You get the idea!

Ok, now I have defined my API, but am I adhering to our corporate standards?

According to Apiary, I am -

But where are these standards set within Apiary?
I can view/edit these, once I have been assigned the Architect role within Apiary.

Now I will activate the British spelling rule -

Btw. the best English is spoken in Ireland, Dublin in fact.

I can, of course, add new rules to enforce my organisation's style guide.

Next to GitHub synchronisation -

I set this up via the Account page -

Then I can go back to the Editor  and leverage the GitHub connection

I choose my /apis repository

Now back in the Editor...

Note the Push button above.

Simple yet succinct!

Get started at

No comments: