Apiary

What are the resources exposed in your API? Look at the terms in your application domain. Probably not all of the terms are resources on their own. Some of them represent resource attributes or affordances (i.e. the actions a resource might afford).

For example: A door may be a resource whereas color and door handle are its attributes, and open and close are the actions the door may afford.

Break down the domain terms, create their data models, and where appropriate, mark these models as resources.

Often a resource may have more than one state. The door may be closed or opened. A message may be drafted, sent or archived.

You may draw a finite state machine diagram to identify the states of your resources and discover the relations between resources. This state machine diagram will help to recognize what resources are really needed and what resources are just data attributes. In addition, the finite state machine diagram helps you to understand how the API might be implemented.

At this point, you should have a clear idea of your API’s architectural style, resources, relations and the API style guide. It is time to formalize these in one of the API Description formats like API Blueprint or Swagger. Using an API Description format helps you to design and prototype your API without writing any code.

Log into Apiary, create a new API project and write everything we have discussed so far into the Apiary editor.

If you are unsure about what API Description format to use check the Choosing the right format article.

## Message [/message/{id}]
- Parameters
    - id: 1234 (number) - Internal id of the Message

- Attributes
    - recipient: /recipient/1234 (string) - URL of the Recipient of the Message
    - text: Hello World! (string) - Text of the Message

### View [GET]
- Response 200 (application/json)
    - Attributes (Message)
                            

To get started with API Description formats review its tutorials the API Blueprint tutorial or the Swagger tutorial.

To enable quick prototyping, Apiary provides you with a hosted Apiary Mock server. Anytime you edit your API description, the mock server gets updated so you can immediately use the prototype.

You can interact with the Mock server directly from the Apiary Documentation console.

You can also call the Apiary Mock server from a command line, using a HTTP client (such as Paw) or directly from your API client.

$ curl http://private-f8032-howtobuildapi.apiary-mock.com/message/1234
{
  "recipient": "/recipient/1234",
  "text": "Hello World!"
}
                            

The Apiary Mock Server will enable you to quickly iterate on your API designs as well as allow you to start working on an API client before the API server is implemented.

Having your API description on GitHub will make versioning, sharing and collaboration a lot easier.

Apiary provides a GitHub Syncoption, which keeps your API description in Apiary synchronized with the latest changes on GitHub and vice versa. Thanks to GitHub Sync you can focus on version control and collaboration without worrying about the API Documentation or Mock Server. GitHub Sync will always keep them up to date.

Furthermore we strongly encourage you to utilize the GitHub flow while iterating on the API design. Apiary offers complete GitHub Integration so you can freely create and switch between the branches while working on your API description.

Make sure to provide meaningful commit messages while submitting a new version of API description.

$ git log --pretty=oneline --abbrev-commit
ba82477 Explain rate limits
e191752 Add rate limiting
f5c4576 Introduce `archive` and `unarchive` actions for the `Message` resource
2049da5 Add the `Message` resource
d1ca0d1 Initial proposal of the API design
                          

Descriptive commit messages in your API description contribute to the overall clarity of communication between API design stakeholders, which eases the navigation between different iterations of an API design.

The sooner you get feedback from API consumers and stakeholders, the better it will be for your API design. Before moving on to the development or the consumption make sure your API description is approved and all remarks are addressed.

Circulate Apiary Documentation with everybody involved in the whole API flow. Ask them for a review of the API description on GitHub. Make sure the API description is conforming to the Style Guide.

With the API description approved, you can move forward to server development, and—using the Apiary Mock Server—to building its clients in parallel.

Once approved, the API Design you have created in the Design and Prototype phase represents a contract with everybody involved in the API lifecycle. You can think of the API description as a formalized agreement between the API provider and API users or the API product owner and API developers.

When it comes to the implementation of this contract, you’ll want to check regularly that it is conforming to the contract, especially when either one changes. If the contract (API design formalized in the description) changes, you’ll need to verify the implementation is still matching the contract (and vice versa).

To make the monitoring of the contract and implementation changes easier, we suggest that you put the API description into the same repository as the implementation.

Apiary comes with seamless GitHub Sync so your API description stored on GitHub always stays in sync with Apiary. If you want to utilize the GitHub flow while you are working on multiple versions of API descriptions, you can take advantage of the complete Apiary GitHub Integration.

In either case, make sure your API description is right next to the code so you always know what the implementation should conform to.

Finally the moment we all love–writing the code!

It is completely your choice what programming language, framework or platform you are going to use to implement your API. The hard work of writing the implementation is up to you, but Apiary is here to help you verify your implementation.

The next few steps will teach you how to test your implementation locally or as part of a continuous integration.

Testing an API locally with Apiary is easy. You do not have to write any tests because you already have your API description.

Apiary has created the API testing framework Dredd. With Dredd you can test your API implementation locally against its API description in an instant.

The way it works is quite easy. After the installation and setup of the Dredd, run

$ dredd
                        

The Dredd tool will start a local instance of your server, take your API description and exercise every endpoint found in the description against the locally run server. It will report any disparities and errors.

Whether you want to test at leisure or as part of a test-driven development workflow, Dredd is here to help.

Once you are familiar with the local testing with Dredd, you can set a continuous integration (CI) service to test your API implementation. Dredd and Apiary support all of the popular continuous integration services.

Applying continuous integration and hosting your API description in the same repository as your implementation enables automatic test runs when anything changes. This assures your API implementation is in accordance with the API description.

Set up a continuous integration in your API implementation repository to be sure that your server is always implementing what is said in your API description.

To help you even further with the testing of your API Implementation, Apiary offers the go-to place for your API test results. Regardless of whether your tests were run locally or in a continuous integration, Apiary Test Reporter offers a comprehensive and easy to use overview of all API Implementation tests.

Visit the Apiary Test Reporter and set up its integration with your local development and continuous integration tests.

With everything implemented and tested as described in the API description, you can deploy your API.

No matter where you deploy your API it is a good idea to add both operational and functional monitoring so you can follow the health of your service and analyze the API usage in the Analysis Phase.

The simplest way to deliver your API to its users is to hand them the API description. Some of the API description formats are easy to read and others are easy to be processed by another program.

If your project is open sourced on GitHub, provide the link to the API description repository so you can get comments directly from users or maybe even a pull request.

We believe the best way to deliver your API is to hand out the Apiary Interactive API Documentation. To do so, simply copy its URL and share it with your API users. This is as simple as sharing your API description directly, but it will provide the user with a much better experience than reading an API description and there are many tools to help in using the API.

If you are using Apiary GitHub Sync and your GitHub repository is public, your API users will be able to see its API description and submit pull requests to it. Do not forget that your Apiary Interactive API Documentation is always in sync with your API description on GitHub, and if you have set up the continuous integration it is always tested.

Share your Apiary Interactive API Documentation URL with your API users.

If you would like to embed your Apiary Interactive Documentation in your website and customize its look and feel, you can do so with the Apiary Embedded Documentation.

A great example of an embedded and customized Apiary Interactive API Documentations can be found at CSAS’s developers portal.

Based on your organization's requirements, you might want to employ an API management system to publish, promote, and monitor your API. This may also include the support of API consumers.

There is a plethora of API management tools and solutions. We suggest picking a solution that best matches your needs and plans for the API. If your organization is already using an API management tool, you may embed Apiary Documentation in it.

The first step to understand an API is to read its documentation. A wise man once said: “An API is only as good as its documentation”. That is why Apiary automatically provides your API with the best API interactive documentation.

To start consuming an API read its documentation and identify the API parts you want to interact with.

The Apiary Documentation console enables you to interact directly with your API without the need to leave the documentation.

With the console you can make API requests to learn about the behavior of the API and how to use it.

To further speed up and simplify the consumption of your API, Apiary Documentation comes with Code Examples in variety of languages.

Copy and paste the code examples in your favorite language and run the request. The code example always includes the full URL of the request be it mock or deployed API.

Apiary Traffic Inspector is a debugger for your client’s calls. With it, you can pinpoint where a problem is in a client server communication.

With every call, you see what data has been sent by the client and what was sent by the server in response.

Every call from any client to the Apiary Mock Server is recorded. You can also monitor calls made to your deployed API using the Apiary Proxy feature.

With Apiary Mock Server you can start working on your API client before (or in parallel) to API development.

Just point your client to the same Apiary-hosted stub implementation you have used to verify your API design in the Design and Prototype phase.

While working on the client, you can use the Apiary Traffic Inspector to debug the traffic between the client and server.

The sooner you start working on your API client, the sooner you might discover and address potential problems with your API design and the sooner you will deliver your client to the market.

If your API is already developed and deployed, you can build your API client using the Apiary Proxy.

The Apiary Proxy feature relays your requests made to your deployed API. It also records all the traffic and reports it to the Apiary Traffic Inspector for debugging.

There are numerous ways to collect feedback about your API.

Every phase of the API design workflow involves different stakeholders working on the API.

During the Design and prototype phase the input from API product owners, organization architects and API consumers is essential for good API design.

The Development phase brings challenges to server developers. Their feedback might help improve both performance and security of the API.

Finally, the Delivery and Consumptions phases put your API to the ultimate test by its users. Here you may learn if the API is delivering what was expected, verifying it as a product.

Analyze the feedback during every phase. Often, the input can be immediately reflected in an updated version of your API design, restarting the API workflow.

You do not have to wait until all the phases are passed to address a feedback. Thanks to Apiary, you can can quickly iterate in your API workflow. With the integrated tools you can rest assured everything is up-to-date with any API description change. And if your API implementation gets out of sync, you are immediately informed thanks to the testing in CI.

It is difficult to come with the right API design in the first pass of your API workflow. Do not hesitate to iterate over and over through the whole API workflow and its phases. Apiary has you covered.