# API Design Guide Documentation  ## Metadata - Author: [[Postman]] - Full Title: API Design Guide Documentation - Category: #articles - Summary: A good API design is simple, consistent, and easy to use, with clear resource names and base URLs. APIs should return proper HTTP status codes and useful error messages in a standard format. Versioning and clear communication about changes help keep APIs reliable and easy to maintain. - URL: https://www.postman.com/postman/postman-team-collections/documentation/cvg32o0/api-design-guide ## Highlights - A well-designed API is easy, and intuitive to use. ([View Highlight](https://read.readwise.io/read/01k0qcpg79jteafmrxm3pwfhne)) - Always keep in mind these following points while designing the URL for your resources. • There should be only 2 base URLs per resource. One to fetch the collection; the second one for a specific element in the collection. • Verbs should be kept away from URLs, instead use nouns. • Avoid mixing plurals and singulars for your resource names. Stick to one and keep it consistent for all your APIs • Use concrete names for your resource rather than abstract ones. For e.g, if you are designing an API for blogs and articles, consider exposing `/blogs`, `/articles` rather than `/items` or `/assets`. ([View Highlight](https://read.readwise.io/read/01k0qd7pq434x0jwrs8x22ph7t)) - It's best to keep the base resource URLs as lean as possible. Complex result filters, sorting requirements and advanced searching (when restricted to a single type of resource) can all be easily implemented as query parameters on top of the base URL. ([View Highlight](https://read.readwise.io/read/01k0qdd1p7gd1rj354y9bxw0aq)) - In some cases, you can also use query params to populate or filter out information from a response. Also whatever query parameters you decide to use, keep it consistent across your endpoints. ([View Highlight](https://read.readwise.io/read/01k0qdd8p94jfsbp1zy3absqbm)) - It is almost never a good idea to return all resources of your database at once. Consequently, you should provide a pagination mechanism. A really simple approach is to use the parameters offset and limit, which are well-known from databases. ([View Highlight](https://read.readwise.io/read/01k0qdefg67124rccnk03a5ask)) - {{url}}/cats?offset=1&limit=10 API to fetch cats using paginated API. If the client omits the parameter you should use defaults (like offset=0 and limit=10) ([View Highlight](https://read.readwise.io/read/01k0qdffmm0hqxa2bs9e5eqdpf)) - Use a unique query parameter for each field that implements filtering. For example, when requesting a list of tickets from the /cats endpoint, you may want to limit these to only those with color white. This could be accomplished with a request like `GET /cats?breed=birman` ([View Highlight](https://read.readwise.io/read/01k0qdha3wj1f4kb52hcsegjm0)) - When the client raises a request to the server through an API, the client should know the feedback, whether it failed, passed or the request was wrong. HTTP status codes are a bunch of standardized codes which has various explanations in various scenarios. The server should always return the right status code. ([View Highlight](https://read.readwise.io/read/01k0qdja4rm340e5xa3ptg8060)) - Always version your API. Versioning helps you iterate faster and prevents invalid requests from hitting updated endpoints. It also helps smooth over any major API version transitions as you can continue to offer old API versions for a period of time. ([View Highlight](https://read.readwise.io/read/01k0qdjphbcywz380fx79zt1wq)) - There are mixed opinions around whether an API version should be included in the URL or in a header. Academically speaking, it should probably be in a header. However, the version needs to be in the URL to ensure browser explorability of the resources across versions ([View Highlight](https://read.readwise.io/read/01k0qdkw36f5ybcn4pjg7zngdq)) - Just like an HTML error page shows a useful error message to a visitor, an API should provide a useful error message in a known consumable format. The representation of an error should be no different than the representation of any resource, just with its own set of fields. ([View Highlight](https://read.readwise.io/read/01k0qdt8m5c648byxfmz7d4vqg)) - The API should always return sensible HTTP status codes. API errors typically break down into 2 types: 400 series status codes for client issues & 500 series status codes for server issues. ([View Highlight](https://read.readwise.io/read/01k0qdv1rwq3tewdwcbqs9ke9g)) - A JSON error body should provide a few things for the developer - a useful error message, a unique error code (that can be looked up for more details in the docs) and possibly a detailed description. JSON output representation for something like this would look like: Plain Text { "code" : 1234, "message" : "Something bad happened :(", "description" : "More details about the error here"} ([View Highlight](https://read.readwise.io/read/01k0qdvs30zdfyhg6jbx80z47z)) - Validation errors for PUT, PATCH and POST requests will need a field breakdown. This is best modeled by using a fixed top-level error code for validation failures and providing the detailed errors in an additional errors field, like so: Plain Text { "code" : 1024, "message" : "Validation Failed", "errors" : [ { "code" : 5432, "field" : "first_name", "message" : "First name cannot have fancy characters" }, { "code" : 5622, "field" : "password", "message" : "Password cannot be blank" } ]} ([View Highlight](https://read.readwise.io/read/01k0qe2v63sjtkhebwf2bnctjg))