APIs as an Enabler: How to Get Out of Your Customers' Way

In today’s fast-paced digital landscape, APIs have become the backbone of modern software development. But what separates a good API from a great one? The answer lies in a simple principle: get out of your customers’ way.

The Problem with Over-Engineered APIs

Too often, API designers fall into the trap of trying to anticipate every possible use case. They create rigid structures, complex authentication flows, and unnecessary abstractions that ultimately hinder rather than help developers.

Consider this example:

// Over-engineered approach
api.users.management.operations.list({
  filters: {
    status: {
      equalTo: "active",
      options: {
        strictMode: true
      }
    }
  }
});

// Simple, effective approach
api.users.list({ status: "active" });

The second approach gets out of the developer’s way—it’s intuitive, readable, and accomplishes the same goal with far less ceremony.

Principles of Enabling APIs

1. Predictable Patterns

Consistency is key. If your API uses RESTful conventions, stick to them everywhere:

GET    /api/2/users      # List users
POST   /api/2/users      # Create user
GET    /api/2/users/:id  # Get specific user
PUT    /api/2/users/:id  # Update user
DELETE /api/2/users/:id  # Delete user

Developers should be able to predict your API’s behavior without constantly referencing documentation.

2. Clear Error Messages

When something goes wrong, don’t make developers guess. Provide actionable error messages:

{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "The email address 'user@' is not valid",
    "field": "email",
    "suggestion": "Ensure the email includes a domain (e.g., user@example.com)"
  }
}

3. Thoughtful Rate Limiting

Rate limits are necessary, but communicate them clearly:

HTTP/1.1 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
X-RateLimit-Reset: 1609459200

Include these headers in every response so developers can build retry logic proactively.

4. Comprehensive, Searchable Documentation

Your API documentation should be:

• Complete: Every endpoint, parameter, and response documented
• Searchable: Developers should find what they need in seconds
• Interactive: Live examples and “Try it” functionality
• Up-to-date: Documentation that matches the current API version

Real-World Example: OneLogin’s Approach

At OneLogin, we’ve rebuilt our developer experience around these principles. Here’s how we list users in our v2 API:

curl https://api.us.onelogin.com/api/2/users \
  -H "Authorization: bearer YOUR_TOKEN"

That’s it. No complex setup, no unnecessary parameters, no ceremony. We return sensible defaults and let developers override them when needed:

# Need pagination? Add it.
curl https://api.us.onelogin.com/api/2/users?limit=100

# Need filtering? Add it.
curl https://api.us.onelogin.com/api/2/users?status=1&firstname=John*

The Impact of Getting Out of the Way

When you design APIs that enable rather than constrain, you:

1. Reduce time-to-integration: Developers get up and running faster
2. Increase adoption: Lower friction means more developers choose your platform
3. Improve satisfaction: Happy developers become advocates
4. Enable innovation: Developers build solutions you never imagined

Takeaways

As you design your next API, ask yourself:

• Am I making assumptions about how developers will use this?
• Can I simplify this without losing functionality?
• Would I enjoy using this API if I were the customer?

Remember: The best API is one that feels invisible—it just works, intuitively, without getting in the way.

What’s Next?

Ready to experience an API designed with these principles in mind? Check out our Quickstart Guide and see how quickly you can integrate OneLogin’s APIs into your application.

Have thoughts on API design? We’d love to hear from you! Reach out on GitHub or Twitter.