How to Design a REST API That Doesn’t SUCK

How to Design a REST API That Doesn’t SUCK

Today, I'll share six easy tips for designing a great REST API. Even big companies overlook these things, making their APIs hard to use. Most content online focuses purely on the technical aspects of developing a REST API—how to use FastAPI, how to host an API in the cloud, those kinds of things. We've also done videos about that, but what does it actually take to design an API that's a pleasure to use and integrates well with other systems? It's not that hard, but it saddens me that even big companies with APIs used by millions of users don’t do the simple things I'll talk about today. Make sure you stick around for the last tip; it’s a really nice thing that I wish more APIs would do. Let’s dive in.

1. Follow Standards

One of the most common standards you'll find is OpenAPI. This is basically an API description standard that you can use to generate documentation, a website where you can test the API, and similar features. Here’s an example of what such a specification document looks like:

(
  "title": "API Title",
  "version": "1.0.0",
  "description": "API Description",
  "servers": [
    {
      "url": "http://api.server.url",
      "description": "Server Description"
    )
  ],
  "paths": (
    "/quizzes": {
      "get": {
        "description": "Get quizzes",
        "responses": {
          "200": {
            "description": "A list of quizzes"
          )
        }
      }
    }
  }
}

We wrote this manually because our current framework doesn’t generate it automatically. However, some tools like FastAPI can actually generate this specification for you automatically from endpoint names, descriptions, arguments, and so on. Incorporating standards like OAuth for authentication is also crucial. For example, Stripe uses an API key which is part of the OAuth standard.

Another important standard is the RESTful standard, which is one of the most common types of APIs you'll encounter. REST stands for Representational State Transfer. It means the representation of a resource state is sent to an HTTP or HTTPS endpoint. There are naming conventions for RESTful APIs that you should follow, such as naming collections in the plural form (e.g., /customers instead of /customer). Moreover, use the right HTTP verb for the appropriate action—GET to fetch, POST to create, DELETE to delete, and PUT or PATCH to update resources. Consistency and adherence to these standards make your APIs more predictable and easier to use.

2. Be Consistent

Consistency is key. Use the same formats everywhere for dates, ranges, query parameters, and other elements. For example, Stripe’s API has an introduction section that outlines all the standardized components, including how pagination works.

However, some APIs like PayPal may have inconsistencies. For instance, in PayPal’s API, the endpoint to get an order by ID has a different structure and doesn’t consistently use identifiers across different resource types.

Ensuring your API is consistent in naming conventions, error handling, and versioning makes it significantly easier to use.

3. Keep Things Simple

Simplicity enhances usability. Implement sensible defaults for arguments. For example, Moneybird’s API has default values for its parameters, making the API easier to use without needing to supply every optional field.

Another approach is to use clear and simple date and time formats. Complex formats that require users to think about time zones and unnecessary details like seconds should be avoided.

4. Write Clear Documentation

Clear documentation is vital. Include examples of API requests in various formats like curl and different programming languages. For example, Stripe includes examples for Python, which is very helpful.

Apart from code examples, explain what the fields mean. Stripe's documentation thoroughly describes each field in a resource object, making it clear what each field represents. In contrast, APIs like Moneybird and Interactive Brokers often lack this kind of clarity, making them harder to use.

5. Make It Easy to Navigate

Your API should be easy to navigate. For example, if you have an order object, users should be able to get to the customer object easily, and vice versa. Stripe resolves this well by linking related entities within its API structure.

In contrast, PayPal’s API has gaps. For instance, transaction objects don’t clearly link to their respective orders or invoices, which can be frustrating for users.

6. Support Custom Data for Easier Integration

Adding support for storing custom data within objects in your API is immensely useful. This allows users to store additional information without altering the core structure of the resource.

APIs like Moneybird implement custom fields, while Stripe uses a metadata dictionary for storing custom data, making integration with other systems easier.

Additional Tips

1. Use Versioning: Include version numbers in your API URL for backward compatibility.
2. Clear Error Messages: Use standard HTTP status codes and provide detailed error messages.
3. Protect Your API: Implement rate limiting, use HTTPS, and validate inputs to prevent common attacks like SQL injection.
4. Add Support for Webhooks: Allow external systems to react to events within your API.
5. Provide SDKs: If possible, offer SDKs in popular programming languages to simplify API integration.

Keywords

• OpenAPI
• OAuth
• RESTful API
• Consistency
• Sensible Defaults
• Clear Documentation
• API Navigation
• Custom Data Integration
• Versioning
• Error Handling
• API Protection
• Webhooks
• SDKs

FAQs

Q: What is OpenAPI and why is it important?
A: OpenAPI is an API description standard that helps generate documentation and interactive websites for testing APIs. It ensures your API is documented in a standardized way, making it easier to understand and use.

Q: How can I ensure my API is consistent?
A: Use the same formats for dates, ranges, and query parameters. Follow naming conventions and be consistent in error handling and versioning.

Q: Why should I implement sensible defaults in my API?
A: Sensible defaults reduce the burden on users to provide every possible parameter, thereby simplifying API usage.

Q: What makes good API documentation?
A: Good documentation includes examples in various programming languages, detailed explanations of fields, and comprehensive descriptions of what the API does.

Q: How do custom data fields improve API integration?
A: Custom data fields allow users to store additional information within API objects, facilitating easier integration with other systems and enabling richer functionality.

Q: What are some additional practices to secure my API?
A: Implement rate limiting, use HTTPS for all requests, and thoroughly validate inputs to defend against attacks like SQL injection.

And there you have it! Following these steps will help you design an API that’s not only technically robust but also user-friendly and easy to integrate.