New API Documentation Beta

Hello everyone!

Please check out our new API documentation here! We would love any feedback and to hear about any issues. You can leave feedback in the top left within the docs, or comment here!

These new docs include:

  • New user interface - single page
  • Better search functionality
  • Automated QA for the accuracy of information
  • Example payloads & responses for every endpoint
  • An OpenAPI spec

We’ve been working on improving the toolchain around our API documentation, and we took this as an opportunity to also upgrade the docs!

You can find our OpenAPI spec here. OpenAPI is an industry standard that strictly defines an API in a machine readable way. This allows us (and you!) to take advantage of open source tools that automatically generate libraries, tests, mock servers, etc.

Let us know what you think!

Thanks,
Ross

2 Likes

@Ross_Grambo,

I’ve only had a quick look. The new features you mention look good. But there’s no Explorer. Are the new docs augmenting the old or replacing them? Will the Explorer be gone in favor of just cURL and the added documentation of payloads/responses?

Thanks,

Larry

1 Like

Great question. Currently, we’re going to re-use the existing explorer as it’s own page. It’ll be at some other path, like “/explorer” (this will happen within the next few weeks). It’s working now, but it needs some updates.

As for our long term plan, we’re not yet sure. Some of us want to add “try it” buttons in the examples on the right, some want to upgrade the explorer and keep it separate, and some don’t care for the explorer at all.

Until some decision is made, it’ll stay as a single page next to these docs!

2 Likes

I vote to keep the Explorer or an equivalent functionality! I find it really useful for quick checking/testing sometimes, and also a valuable tool for people getting started with the API. I know one can use Postman and such, but Explorer is even quicker/easier.

4 Likes

Thanks, Ross. I appreciate that and see the tradeoffs. I agree with all the points in Phil’s post.

1 Like

First, I was afraid when I saw the very long single page… because one of your competitor (T…) did the same, and I totally hate it, because it takes 100% cpu to scroll and find anything.

Then, I started to scroll and navigate… and finally, it’s quick and performs very well !
I can’t tell about the explorer, because I don’t use it… but the navigation + treeview works well!

The search is nice too, no longer need to quit and use google to search in the api :smiley:

3 Likes

Looks good. I was really happy with the existing doc, so :man_shrugging: :slight_smile:

1 Like

The url has now changed and we threw in the API Explorer & a basic landing page.

The docs are at Build an app with Asana & the explorer is at Asana API Explorer.

2 Likes

:partying_face:

1 Like