Designing GET for Collections in REST APIs

When designing APIs, the GET method is one of the most commonly used HTTP methods. It’s used to retrieve data, either as a full list or a single resource. In this article, we focus on getting collections of resources.

🔍 Use Case

Let’s say we’re building a service that allows users to manage accounts. We want to allow users to:

• List all accounts

📄 Designing the Endpoint

Use a plural noun for the resource name:

/accounts

This will return:

• [] if no data exists
• or a list of accounts like:

[
  {
    "login": "adoe",
    "name": "Adrian",
    "surname": "Doe",
    "role": "ADMIN",
    "rank": 20
  }
]

Always return HTTP 200 OK even for an empty array.

✏️ Naming Tips

• Use hyphens and slashes for readability:

  /accounts/ldap
  /accounts/db
  /accounts/emails
  

• Avoid compound names like /ldapaccounts.

• Use singular names only if there’s one global resource:

  /configuration
  

✅ Summary

To get a collection of resources:

• Use plural nouns (/accounts)
• Return empty arrays when no data is present
• Stick to HTTP 200 for success
• Keep naming consistent and clean