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 still allows you to create a beautiful and interactive API reference section!
OpenAPI vs. Manual API editor
Some advanced API Reference functionality is not supported in the manual API editor:
Complex OpenAPI 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
ReadMe's Node API SDK
Rendering response object schema descriptions and details
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**
For your API reference docs, you will first need to set up your first API setting, which creates the base properties of your API such as the name and base URL. As a rule of thumb, you will want to create a new page for each HTTP endpoint in your API!
## Describe your API
For starters, you'll want to set the base properties of your API, such as the name and base URL.
You have three authentication methods to choose from:
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.)
### 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.
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 information on defining these endpoints.
## API Setup
The API setup is where you can define your endpoints and the parameters associated with them. As a rule of thumb, you will want to create a new page for each HTTP endpoint in your API!
### Add Your Endpoints and Parameters
Go to the Reference Docs tab and add a page like you normally would. On the top-left, there is a dropdown button. This will let you select the type of page you want, select API endpoint to bring up the API builder.
After that, describe your API's URL and parameters, then optionally add a response example or two. Be sure to add all the necessary params in your endpoint description. You have the option of adding path, query, body, or header params here.
Lastly you can select if you want [authentication](🔗) enabled or disabled for this endpoint.
If ":param" is found in your URL, it will be replaced. So, something like `
<http://test.com/item/:id?color=:color`> would become `
If not, it will either be appended as a query string (if the endpoint method is GET) or posted based on the "Content-Type" in API explorer (if anything other method type).
️ Naming limitations
Please note that due to some current limitations in our API explorer, we currently do not support the creation of multiple API endpoint pages for the same HTTP method and path.
### Required Parameters
Path parameters will always be required, but for query, body, and header they will be optional by default. However if you click on the star next to the parameter, it will make it required.
### Object Definitions
You can add object schemas that can be reused across endpoints by selecting object/hash and clicking on manage definitions. It will take you to our object wizard, which lets you add the parameters of the object schema.
Nested Object Parameters
Tip: You can do nested object params by using either dot notation (`
user.id`) or bracket notation (`
### Test It Out!
You should be ready to go! Visit your page, and play around with the API Explorer. Every API is unique; let us know if something doesn't work and we'll do what we can to fix it!
### Raw Body Content
When you setup an API endpoint, you have the option to use raw body content for the body parameters
Raw body content refers to the ability for you to document APIs that have no named JSON parameters. Something like the following in cURL:
This also works for other primitives, arrays and objects.
## 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.
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. 😉
**_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.
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!
**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:
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.