Manual API Editor

Provide testing and interactivity to your API endpoint documentation.

While the recommended approach to writing API reference docs is with an OpenAPI file, the specification can be confusing and these files can be difficult to maintain. That's why we also have a manual editor, which allows you to create a beautiful and interactive API reference section!

🚧

OAS vs. manual API editor

Some advanced API Reference functionality is not supported in the manual API editor:

  • Complex OAS features such as allOf, anyOf, and discriminators
  • Choosing from multiple server urls or using server variables
  • Rendering complex nested objects
  • Supporting multiple authentication methods
  • Selecting default autogenerated code sample languages
  • multipart/form-data content types

If you need this functionality for your API Reference, we highly recommend documenting your API using the OpenAPI Specification. We've had customers outsource this task on freelancer sites like Upwork with good success if you aren't able to do this in house!

Configure your API

You must define several base characteristics about your API before you can add endpoints pages. In the ReadMe dashboard, navigate to API Reference > API Definitions > Add your first API

If you have an OpenAPI file, upload that instead!If you have an OpenAPI file, upload that instead!

If you have an OpenAPI file, upload that instead!

Describe your API

Name your API (this will be become the top-level category label that your pages will be under) and set your API's base URL.

Authentication

You have three authentication methods to choose from:

  1. API Key (Note: for this option, you'll be able to specify whether the API key is sent in the header or the query string of the request, as well as the name of this API key and a default, if applicable. You can also specify several API keys, if needed.)
  2. Basic Auth
  3. OAuth 2.0

Try It!

The "Try It!" button allows your users to run requests directly from the browser and view an actual response from your API. This feature is automatically enabled, but you can disable it by unchecking the "Enable API Explorer" option under Additional Options. The API Proxy is used to prevent CORS permission errors, so if you need to disable that feature (the "Enable API Proxy" option under Additional Options) for any reason, make sure you allow try.readme.io if you want the API Explorer to work as expected.

Other

You can add additional API Headers (see the API Headers section of the form) which will add any additional headers of your choice to every request (and code sample, if you're automatically generating them). You can also select MIME types (see the Mimetypes section of the form) of your API requests and responses, which will configure the Content-Type and Accept headers accordingly.

We will generate code samples for you automatically (and we recommend this approach, see Don't Hate, Auto-Generate below!), but if you would like to display your own custom code samples instead, simply uncheck the "Enable auto code samples" option. If you turn off auto code samples, we will still display any custom examples that you have added to particular endpoints.

When you are done adding your API Settings, head over to the newly created category and start defining your endpoints! See the next section for several best practices as you start defining these endpoints.

Best Practices

There are significant improvements to the API Reference section in the new docs design (as of Q2 2021), including better handling of request and response examples and better handling of nested parameter definitions. You can read the full highlights here, but in this section we'll go over some of our recommendations for writing docs in our Manual API editor that take full advantage of the features available in the reference section.

  • Get Plenty of REST Before Defining Parameters 😴 While ReadMe and its reference docs can be used for many different use cases, the API Reference section truly shines with HTTP/REST APIs. The "API Endpoint" page types are the best place to document each of the endpoints of your REST API. If you're trying to use the API Reference section to document non-REST APIs or other documentation scenarios, we recommend using the Guides section instead, or sticking with the standard "Page" type.
You can specify the page type in this dropdown next to the page title.You can specify the page type in this dropdown next to the page title.

You can specify the page type in this dropdown next to the page title.

    If you are in fact documenting a REST API, you're in luck! We have built-in fields where you can document parameters (whether they're in the request body, header, query string, etc.) with support for all kinds of different parameter types. These parameter definitions will render interactive forms in the reference section that provide helpful validation to the user about the data your API will accept. Enums will render a dropdown, numbers will render number inputs, required fields will be marked with "required" in a scary red color... you get the idea! We strongly recommend this approach to defining your parameters. Trust us: your users will love and appreciate it far more than any table written in Markdown. πŸ˜‰
A body parameter, defined in the Manual API editor and more importantly, not in a Markdown tableA body parameter, defined in the Manual API editor and more importantly, not in a Markdown table

A body parameter, defined in the Manual API editor and more importantly, not in a Markdown table

  • Lead By Example, A Feel-Good Film Starring JSON and Friends πŸ“½ Thoughtfully-written documentation is key to your users' success with your APIβ€”which is why we looooove when docs are chock-full of helpful examples. Examples are an excellent way to visualize the data format your API will expect and send back in return. Our redesigned reference section (and the OpenAPI Specification more broadly) absolutely shines when it comes to JSON examples. Not only will the reference section automatically populate your form with your request examples, but the redesigned reference section has a comprehensive schema explorer that contains a detailed look at each of your response body parameters.
A request example (defined in the **Example** field), and a response example (defined in the **Results** field). Both defined in JSON! You love to see it.A request example (defined in the **Example** field), and a response example (defined in the **Results** field). Both defined in JSON! You love to see it.

A request example (defined in the Example field), and a response example (defined in the Results field). Both defined in JSON! You love to see it.

    If your API supports JSON payloads, we strongly recommend defining request and response examples (and the more examples, the merrier!) in JSON. And don't forget to specify "JSON" in the language selection dropdown! We also are friendly to APIs that support URL-encoded and XML payloads, but be sure to specify these MIME types [when creating your API definition](https://docs.readme.com/docs/manual-api-settings#design)!
  • Don't Hate, Auto-Generate πŸ’™ For pages with the "API Endpoint" type, the "Example" field is where you can define request examples. While you can write static code samples which will appear just fine in your reference section, we strongly recommend inserting example payloads themselves (and again, JSON works best here!), where the keys of your payload correspond to the names of any applicable body parameters.

    For example, if you have an endpoint that has a body parameter named message and you're attempting to render an example value of "Hello world!", your request example should be confined to the JSON payload itself, like this:

    { "message": "Hello world!" }
    

    instead of a full JavaScript code sample, like this:

    const fetch = require('node-fetch');
    
    const url = 'https://api.example.com';
    const options = {
      method: 'GET',
      body: JSON.stringify({message: 'Hello, world!'})
    };
    
    fetch(url, options)
      .then(res => res.json())
      .then(json => console.log(json));
    

    We recommend this approach because you'll be able to utilize our auto-generated code samples (available in over a dozen languages), which populate parameter values as users type values into the form. Plus, your user can then execute the API request directly from the browser using the "Try It!" button and see a real response from your API! Writing payload-focused examples saves you time since you don't have to maintain docs for multiple languages and will result in a documentation experience that is far more interactive and catered to the preferences of your users.


Did this page help you?