# 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](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")

> 📘 Automatic Path Normalization > > The API Designer automatically ensures that all endpoint paths begin with a leading `/`, as required by the OpenAPI specification. For example, if you enter `posts` as the path, it will be automatically corrected to `/posts`. This helps ensure your API definition remains valid. ### 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

## 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

## 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.
## Currently Unsupported OpenAPI Features in the API Designer We currently don't support all OpenAPI features in our API Designer. If you use any of these features in an endpoint you will be unable to edit them in our UI. However, these endpoints will still render properly in the documentation and can still be updated by editing the OpenAPI file directly.
| Unsupported OpenAPI Feature | Explanation | OpenAPI Documentation | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Additional Properties | The additionalProperties keyword is used within a schema to define whether properties not explicitly defined in the schema are allowed in objects, and if so, what their types should be. | [Dictionaries, HashMaps and Associative Arrays](https://swagger.io/docs/specification/v3_0/data-models/dictionaries/) | | Callbacks/Webhooks | OpenAPI has a feature to define endpoints that will make an API call once an event has completed. | [Callbacks](https://swagger.io/docs/specification/v3_0/callbacks/) | | References | Any endpoint that defines an object using a $ref. | [Using Ref](https://swagger.io/docs/specification/v3_0/using-ref/) | | Common Parameters | Endpoints where parameters are defined at the path level instead of the method, so the parameters are shared between all methods for that URL. | [Describing Parameters](https://swagger.io/docs/specification/v3_0/describing-parameters/#common-parameters) | | Links | Links are an OpenAPI feature that describes how the responses of one endpoint can be used as input for other operations. | [Links](https://swagger.io/docs/specification/v3_0/links/) | | Polymorphism | Polymorphism lets you define a schema that can represent multiple types or models. | [Inheritance and Polymorphism](https://swagger.io/docs/specification/v3_0/data-models/inheritance-and-polymorphism/?sbsearch=Polymorphism) | | Server Variables | Variables can be defined in the base path which can have a preset list of values the user can choose from. | [API Server and Base Path](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/?sbsearch=server%20variables) | | Style | The Style keyword allows configuration on how multiple values should be passed to a parameter. | [Parameter Serialization](https://swagger.io/docs/specification/v3_0/serialization/?sbsearch=Styles) | | XML | Endpoints that accept or respond with XML data. | [Representing XML](https://swagger.io/docs/specification/v3_0/data-models/representing-xml/?sbsearch=xml) |