Building Better REST APIs: A Hybrid Approach with JSend and JSON:API Guidelines

Mon, 01 May 2023 18:00:00 -0600

This hybrid API design guide combines elements from both JSend and JSON:API to create a powerful and user-friendly approach for developing REST APIs. By adopting the best practices from both, this guide offers a consistent and maintainable API design.

Versioning

API versioning can be achieved using a variety of methods such as URI-based route prefix, version in the header of the request, or as a query string value.

The most common approach is using a URI-based route prefix for RESTful routes to define versions. This approach requires including the API version identifier as a part of the URL path, preferably as the first segment. For example, the API endpoint URL could look like:

Decoupling UI Copy From API Error Contracts

Wed, 01 Mar 2023 18:00:00 -0600

Users need human-readable error messages. Software needs stable, machine-readable error identifiers.

Neither should have to parse the other.

That is the boundary I want when building error handling for a web application. The backend should explain what failed in a predictable structure. The presentation layer should decide how that failure is presented to the person trying to finish a task.

In a smaller application, that presentation layer may be the browser. In an enterprise application, it may include a backend for frontend (BFF), a shared message catalog, or a localization service. The deployment diagram can change without changing the boundary.

JSON:API on Coderrob

Building Better REST APIs: A Hybrid Approach with JSend and JSON:API Guidelines

Versioning

Decoupling UI Copy From API Error Contracts