#519 First steps in building an API on Apiary.io

I just signed up for a free account and got going.

Let's look at the first 3 activities in the Apiary workflow -

Here we decide on the domain space semantics and the architectural style to be used.
Then we can jump into the design, creating an API blueprint. Apiary provides you with an excellent editor for doing this.

Just amend the default API Blueprint accordingly.

 Here I change the Name and the Introduction.

As you can see, my api will allow one to create, retrieve, update and delete customers in the CustomersDB.

Here I define the Resource:

I then define the api as follows -

The Result -

Just a couple of points to note, the blueprint is divided into sections.
These are marked by the # symbol.

# is for metadata, such as the api name and definition

FORMAT: 1A entry just identifies the document as an API Blueprint.
Essentially adhering to version 1A of the specification.

Note HOST, this refers to the production URI of your API.

## is for Resources
I have defined 2 -

### is for actions of those Resources

Note the inclusion of the HTTP Method.


The action can include Request / Response definitions -

Let's look at the definition of Get a Customer based on custid -

I click on Get a Customer based on custid -

Before I can Try, I need to Publish.

Once published, I have access to a Mock Server, which I can use for sanity testing.

Here is  the expected Response -

Apiary will also generate the client code in a variety of languages - here is JavaScript -

Here is the full list -

























Apart from the Mock Server - Apiary also has a Debugging Proxy, you can leverage -

The full API Blueprint Specification is here

BTW. Instead of using the API Blueprint to describe your API, you can also use Swagger.
Check out the Apiary doc here

Once the API has been designed, you can share it.
For example, you can invite folks to review it or even go the whole hog and create a team.

As an individualist anarchist, I just invited myself.
Note, one can giving view or edit rights.

I click on the link in the email and quelle surprise -

As the Irish were wont to say, now you're sucking diesel!