Overview

No OpenAPI specification? No problem! ReadMe's API Designer lets you build your API reference directly in the platform with an intuitive visual interface – no YAML or JSON required.

In this guide, we'll walk through creating a Social Media API with endpoints for listing and creating posts. You'll see how easy it is to document your API even if you're starting from a blank slate.

Creating Your API Definition

Let's start by setting up the basic structure for your API:

1. Navigate to API Reference in your ReadMe project
2. Click the + Add button
3. Select Start Building under "Build an API definition from scratch"

4. Enter your API definition details:
   • API Title: Enter a descriptive name (e.g., "Social Media API")
   • Target Host URL: Your API's base URL (e.g., "http://api.example.com")
   • Authentication Type: Select your authentication method (None, API Key, Basic, or Bearer)

5. Click Save to create your API definition

Your new API definition will appear in the left navigation panel, ready for you to add endpoints.

Creating Your First Endpoint (List Social Media Posts)

Let's create an endpoint to retrieve a list of social media posts:

1. In the left navigation, you'll see a default endpoint labeled /new-endpoint
2. Rename this to better reflect your API structure - let's call it "Posts"
3. You'll now see this category in your left navigation

4. Create your GET endpoint for listing posts:
   • Click on the endpoint to edit it
   • Change the title to "List Social Media Posts"
   • Select the GET method from the dropdown menu
   • Set the path to /posts
   • Add a description explaining what the endpoint does (e.g., "Returns a paginated list of social media posts")

Adding Query Parameters

Most list endpoints support pagination or filtering. Let's add some query parameters:

1. Locate the Query Parameters section and click the + button
2. Add parameters for pagination:
   • Add a page parameter of type integer
   • Add a limit parameter of type integer
   • Add any other filtering parameters (e.g., category as a string)
3. For each parameter:
   • Add a description
   • Set whether it's required
   • Provide a default value if applicable

Adding Example Responses

Now let's add an example response to show developers what to expect:

1. Locate the Add example response section on the right side
2. Click the + button
3. Select the status code (typically 200 for successful GET requests)
4. Add a JSON response example that shows a list of posts with typical fields like IDs, content, timestamps, etc.
5. You can add multiple response examples for different scenarios

Creating Your Second Endpoint (Create a Social Media Post)

Now let's add an endpoint for creating new posts:

1. In the left navigation, click the + New Category button if you need a new category, or use your existing "Posts" category
2. Click the + icon to add a new endpoint
3. Set up your POST endpoint:
   • Title: "Create New Post"
   • Method: Select POST from the dropdown
   • Path: /posts
   • Description: "Allows authenticated users to create new posts"

Adding Request Body Parameters

For a POST endpoint, you'll need to define the request body:

1. Locate the Request Body section and click to expand it
2. Set the content type to object
3. Add the required fields:
   • Add a content field of type string and mark it as required
   • Add any additional fields your API accepts (e.g., image_url, tags)
4. For each field:
   • Add a clear description
   • Mark whether it's required
   • Provide any constraints (min/max length, pattern, etc.)

Adding Request Code Samples

One of ReadMe's powerful features is automatic code sample generation:

1. Find the Request Code section on the right
2. ReadMe automatically generates code examples in multiple languages
3. You can also click "Write your own static samples" to add custom examples

Adding Example Responses

Finally, add example responses for your POST endpoint:

1. Click the + button under "Add example response"
2. Add a 201 status code for successful creation
3. Provide a JSON example of the created resource
4. Consider adding additional response examples for errors like 400 (Bad Request) or 401 (Unauthorized)

Testing Your API Documentation

After creating your endpoints:

1. Save your changes
2. Toggle to the "View" mode to see how your documentation looks to developers
3. Test the interactive features to ensure your examples work correctly

Tips for Great API Documentation

• Be thorough with descriptions: Clearly explain what each endpoint does and why
• Provide realistic examples: Use example data that looks like real-world usage
• Document error states: Include examples of error responses and how to handle them
• Use consistent naming: Maintain a consistent style across all endpoints and parameters
• Add "What's Next": Use the "What's Next" section to guide users on related endpoints they might need

By following this guide, you've created a well-documented API reference from scratch using ReadMe's API Designer. Your developers now have interactive, clear documentation that helps them integrate with your API quickly and easily.

Remember, you can always return to the API Designer to add endpoints, update parameters, or enhance your documentation as your API evolves.