Last updated: July 22, 2021

Adding a custom REST API to your Spring Boot project

In a real application basic CRUD operations are often not enough. This is where the custom endpoints of the professional plan come into play.

The tab "Controllers" allows you and your dev team to agree on an API before writing a single line of code. Still the first prototype is directly available for download after the concept has been completed, and you can start implementing the business logic behind it. Let's extend our CarParts example and provide a small search API.

JSON structure of our new example endpoint

Defining the JSON structure

For our example we want to find CarParts that match our search parameters. For this purpose, a date range can be specified within which the spare part must have been released. In addition, a list of supplierIDs can be specified to further narrow down the result.

To enable this query, we first create the Data Objects in the respective tab. Later on we will select them at our endpoint, thus describing the JSON structure of the POST request. We start with the object "DateRange" and the two fields "releaseAfter" and "releaseBefore" (OffsetDateTime).

Creating the DateRange object for our example endpoint

Creating the DateRange object for our example endpoint

Now we can create the second Data Object that describes our input: "SearchRequest" with the fields "dateRange" (with our just created Custom Type) and "supplierIds". For the latter we choose List with the list type Long.

Adding the SearchRequest with the DateRange custom field type

Adding the SearchRequest with the DateRange custom field type

Creating the endpoint

With this we can create our search controller. For our example we only need one endpoint with the HTTP method POST. As input type we select our created object "SearchRequest", as output we choose a List with the already existing type "CarDTO".

In addition to the type List, Page is also available as a response type. This adds pagination to the endpoint - that means only one page of the requested content is returned at once. With the parameters page, size and sort the request can be refined according to the Spring Boot standards.

Our new controller with the search endpoint

Our new controller with the search endpoint

We also added a parameter into our path: {clientId} so that the client can identify himself. The type selection is appearing right after the parameter has been added. We can use this feature on individual methods as well.

If we like, we can discuss and improve the new API further with our dev team. An OpenAPI preview is directly available in Bootify, and after downloading and starting the application, the new endpoint is also visible in Swagger UI.

The custom SearchController in Swagger UI

The custom SearchController in Swagger UI

Our small example is already finished, so we can download the generated code and start with the implementation right away.