Home

The main idea behind the SimplyRESTful framework is that the only difference between two REST APIs is the resource that it provides. This follows from the constraints of REST, primarily the Uniform Interface constraint.

This Uniform Interface constraint also happens to be very difficult to adhere to so most current Web APIs that claim to be REST APIs do not have a uniform interface. Even Web APIs from the same developers or company may differ in how you use different resources in that API. This is why most of these APIs have documentation for every endpoint. A well-known example is the OpenAPI Specification that can be generated automatically based on the code and turned into a user-friendly documentation website using something like Swagger UI or redoc. This works well enough but has the unfortunate downside that your experience with one API usually does not carry over to another API, or only to a limited extent.

Currently, the only available standard for creating a REST API is OData (Open Data Protocol). However, this standard is optimized for data access and manipulation. This makes it less suitable for more generic use, as a uniform interface. Though it's worth noting that it does seem to provide all you need for a REST API.

Building on this idea that REST APIs should only differ in the resources they provide, the SimplyRESTful framework allows you to define your resources as POJOs (Plain Old Java Objects). This provides the flexibility to describe any resource you can design. The SimplyRESTful framework can then provide the implementation for all other parts of the REST API, adhering to the most suitable standards and best practices. Of course, the framework can only provide the REST API part of your API implementation, ensuring a uniform interface. The backend of your API, i.e. retrieving, storing and modifying your resources based on their own specific needs, still needs to be implemented separately.

For example, the SimplyRESTful framework uses HTTP as its protocol, as almost all Web APIs do, and is built on top of JAX-RS. The uniform HTTP access to the REST API is translated by the framework to simple CRUD methods that need to be implemented as part of the backend of your API. Some more examples are that the JSON representation of the resource is deserialized to the corresponding POJO and timestamps are converted from their ISO-8601 representation to java.time.ZonedDateTime objects.

While these examples seems simple enough to implement, the real work goes into deciding what you should translate from, since that is what ultimately becomes the uniform interface of your REST API. And this framework adheres to standards and best practices for this. So the uniform HTTP access adheres to the HTTP standard, correctly implementing how HTTP methods and status codes work (to the extent this is feasible).

This level of uniformity also allows for some generic functionality to be provided by the framework itself, such as filtering the fields within a JSON document. It also provides a solid foundation for even more functionality, even if it cannot entirely be provided by the framework. For example, sorting and querying will always need to be implemented in the backend of the API (if you want acceptable performance, at least) but the framework implements the query parameters that support this functionality according to best practices. In the backend implementation of your API, you do not need to worry about what format or syntax was used or which query parameter it was from. You simply get a standardized query or list of field names for sorting that you can use in your backend implementation.

With this, the SimplyRESTful framework should provide you with a uniform interface for your REST API and allow you to focus on designing the REST API resources you need.