Docs tutorial: Get started with REST API

Goal and proposal

We have Get started using GraphQL, but a similar page does not exist for the REST API. The closest thing to a tutorial for the REST API is How to use the API. We would need to move that section (and potentially other sections in API Docs) to a new page, verify the content, and create a tutorial out of it.

Basic outline

Looking at API Docs, it looks like the page was originally dedicated to the REST API and the GraphQL API was only added at a later point. For this tutorial, we should do the following:

  • Use API Docs as a brief landing page for both the REST and GraphQL APIs.
  • Create a new REST API page that we could populate with content refactored from API Docs as it relates to the REST API. We could move any reference information in API Docs to that page.
  • Move the REST API resources page one level deeper, and create a sibling Tutorial: Get started with REST API page that would mirror Get started using GraphQL.
  • Ensure the tutorial includes a running example that is easy to follow.

Where to place

The tutorial could be a child page of a new REST API page. I could imagine the left navigation would look like this:

  • Use the API
    • REST API
      • Tutorial: Get started with REST API
      • REST API resources

Related issues

Edited by Ashraf Khamis