Should I create a Repository interface and Models based on the end points in a REST app?

[tangara goh]

I am new to Spring Boot and rusty in REST...

Now, I am tasked to created several end points based on the following tags:

Store - access orders
GET /store/inventory - returns pet inventories by status
POST - place an order for a pet

My question is :

Should I create a Store repository interface or Do I create an Order repository interface and then I do it like this ;

Order findById(Pet Id) // assuming 1 order 1 pet

Or should I create a Order repository interface  and then I do it like this

Store findById(Order Id) // this one make more sense to me.

Assuming the later is to be used, I would need to have a entity class Store right ?

Thanks.

[Stephan van Hulst]

Design repositories and web APIs separately. While REST resources may often look like database entities, there are cases where they don't map to each other well.

A StoreRepository only makes sense if you save individual pet stores in a database.

Your REST API doesn't make sense to me. A POST request on a path /store/inventory implies to me that you will be adding an entire inventory to a store, not placing an order for a pet.

It also doesn't make sense to me that you would use a Pet instance as an ID to get an Order from your repository. Instead, I would expect the OrderRepository to look something like this:

public interface OrderRepository {

  public Optional<Order> findById(String id);

  public Optional<Order> findByOrderedPetId(String petId);

  // other methods for retrieving, adding or removing orders

}

[tangara goh]

Stephan van Hulst wrote:Design repositories and web APIs separately. While REST resources may often look like database entities, there are cases where they don't map to each other well.

A StoreRepository only makes sense if you save individual pet stores in a database.

Your REST API doesn't make sense to me. A POST request on a path /store/inventory implies to me that you will be adding an entire inventory to a store, not placing an order for a pet.

I think I better provide the various end points to be more clear:

But, really, I am blur myself...

/pet/findByStatus:
    get:
      tags:
      - "pet"
      summary: "Finds Pets by status"
      description: "Multiple status values can be provided with comma separated strings"
      operationId: "findPetsByStatus"

      parameters:
      - name: "status"
        in: "query"
        description: "Status values that need to be considered for filter"
        required: true
        type: "array"
        items:
          type: "string"
          enum:    - "available", - "pending",  - "sold"
          default: "available"
        collectionFormat: "multi"
      responses:       
      security:
      - petstore_auth:
        - "write:pets"
        - "read:pets"
  /pet/findByTags:
    get:
      tags:
      - "pet"
      summary: "Finds Pets by tags"
      description: "Muliple tags can be provided with comma separated strings. Use         tag1, tag2, tag3 for testing."
      operationId: "findPetsByTags"

      parameters:
      - name: "tags"
        in: "query"
        description: "Tags to filter by"
        required: true
        type: "array"
        items:
          type: "string"
        collectionFormat: "multi"
      
      security:
      - petstore_auth:
        - "write:pets"
        - "read:pets"
      deprecated: true
/pet/{petId}/uploadImage:
    post:
      tags:
      - "pet"
      summary: "uploads an image"
      description: ""
      operationId: "uploadFile"
      consumes:
      - "multipart/form-data"
      produces:
      - "application/json"
      parameters:
      - name: "petId"
        in: "path"
        description: "ID of pet to update"
        required: true
        type: "integer"
        format: "int64"
      - name: "additionalMetadata"
        in: "formData"
        description: "Additional data to pass to server"
        required: false
        type: "string"
      - name: "file"
        in: "formData"
        description: "file to upload"
        required: false
        type: "file"     
      security:
      - petstore_auth:
        - "write:pets"
        - "read:pets"
  /store/inventory:
    get:
      tags:
      - "store"
      summary: "Returns pet inventories by status"
      description: "Returns a map of status codes to quantities"
      operationId: "getInventory"
      produces:
      - "application/json"
      parameters: []
      responses:
        "200":
          description: "successful operation"
          schema:
            type: "object"
            additionalProperties:
              type: "integer"
              format: "int32"
      security:
      - api_key: []
  /store/order:
    post:
      tags:
      - "store"
      summary: "Place an order for a pet"
      description: ""
      operationId: "placeOrder"
       parameters:
      - in: "body"
        name: "body"
        description: "order placed for purchasing the pet"
        required: true
        schema:
          $ref: "#/definitions/Order"     
          description: "Invalid Order"
  /store/order/{orderId}:
    get:
      tags:
      - "store"
      summary: "Find purchase order by ID"
      description: "For valid response try integer IDs with value >= 1 and <= 10.         Other values will generated exceptions"
      operationId: "getOrderById"
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - name: "orderId"
        in: "path"
        description: "ID of pet that needs to be fetched"
        required: true
        type: "integer"
        maximum: 10.0
        minimum: 1.0
        format: "int64"
         delete:
      tags:
      - "store"
      summary: "Delete purchase order by ID"
      description: "For valid response try integer IDs with positive integer value.         Negative or non-integer values will generate API errors"
      operationId: "deleteOrder"
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - name: "orderId"
        in: "path"
        description: "ID of the order that needs to be deleted"
        required: true
        type: "integer"
        minimum: 1.0
        format: "int64"
      responses:
        "400":
          description: "Invalid ID supplied"
        "404":
          description: "Order not found"

I have left out all the common findbyId in /pet/ end point.

Hope you could advise me if there is any change in terms of the Repository interface I should create.

Many thanks for your help again.

[Himai Minh]

You may find this tutorial helpful. You can create a repository class extending the CrudRepository .
https://www.concretepage.com/spring-5/spring-data-crudrepository-example

[Stephan van Hulst]

The endpoints you described do not form a REST API. It's just plain RPC. I'm not saying that's bad, it's fine. It's just not REST.

Based purely on the request URL paths, you'll want at least a PetController and an OrderController, and maybe an InventoryController. For instance, the PetController could look like this (when using JAX-RS):

@Path("pet")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public final class PetController {

  private final PetRepository repository;

  @Inject
  public PetController(PetRepository repository) {
    if (repository == null)
      throw new IllegalArgumentException("The pet repository may not be null.");

    this.repository = repository;
  }

  @GET
  @Path("findByStatus")
  public List<PetSummaryData> findByStatus(@QueryParam("status") List<PetStatus> statuses) {
    if (statuses == null || status.isEmpty())
      statuses = List.of(PetStatus.AVAILABLE);

    return repository.findByStatuses(statuses).stream().map(PetSummaryData::ofPet).collect(toList());
  }

  @POST
  @Path("{petId}/uploadImage")
  @Consumes(MediaType.MULTIPART_FORM_DATA)
  public void uploadImage(
    @PathParam("petId") String petId,
    @FormDataParam("additionalMetadata") FormDataBodyPart additionalMetadata,
    @FormDataParam("file") FormDataBodyPart file
  ) {
    var pet = repository.findById(petId).orElseThrow(NotFoundException::new);

    try {
      var image = FormDataUtilities.getImage(file);
      respository.addImage(petId, image);
    }

    catch (InvalidFormDataImageException ex) {
      throw new BadRequestException(ex);
    }    
  }
}

Note that I made up the classes FormDataUtilities and InvalidFormDataImageException, they are not part of any framework I know of.

Anyway, as you can see from this example controller, it assumes that there is a PetRepository interface that contains methods findByStatuses() and findById() that return Collection<Pet> and Optional<Pet> respectively, and a method addImage().

Only make repository interfaces for entire object graphs that you want to store. For instance, even if you have a separate table in your database that stores images, don't create an ImageRepository because you'll only ever want to store or retrieve an image related to another specific object in your database, such as a pet. You'll probably want a PetRepository and an OrderRepository, and you'll probably want an InventoryRepository as well that stores the inventory of a store.

I'm not sure what your supervisor expects of the GET /store/inventory endpoint, but I imagine it would return a response like this:
{  "available": {    "cats": 2,    "hamsters": 4,    "fish": 23,    "rats": 15  },  "pending": {    "dogs": 1,    "rabbits": 2  },  "sold": {    "cats": 5,    "dogs": 3,    "fish": 36,    "hamsters": 12,    "rabbits": 7,    "rats": 24  } }
Such a controller could look like this:

@Path("store/inventory")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public final class InventoryController {

  private final InventoryRepository repository;
 
  @Inject
  public InventoryController(InventoryRepository repository) {
    if (repository == null)
      throw new IllegalArgumentException("The inventory repository may not be null.");
 
    this.repository = repository;
  }
 
  @GET
  public Map<PetStatus, Map<PetCategory, Long>> getInventory() {
    return repository.getSummary();
  }
}

[Himai Minh]

For the above example, in Spring, we use @Autowired to inject the PetRepository.

[tangara goh]

Stephan van Hulst wrote:The endpoints you described do not form a REST API. It's just plain RPC. I'm not saying that's bad, it's fine. It's just not REST.

Based purely on the request URL paths, you'll want at least a PetController and an OrderController, and maybe an InventoryController. For instance, the PetController could look like this (when using JAX-RS):

Oh no....cos I actually tweaked a sample Spring REST project to fit into this requirements.

The sample project I used is :

https://projects.spring.io/spring-petclinic/#quick-start

And the this project will be using JPA so I have used extened JpaCRUDRepository in all my interfaces.  Is it ok to do it that way ?

Furthermore, I am thinking of later abstracting out the common findById across all the entities by using

SpEL Expressions as outlined in 5.3.7 at https://docs.spring.io/spring-data/jpa/docs/current/reference/html/@reference

Cos there are so many CRUD and I am thinking just replacing it with a T<CRUD>(Note: I am pretty new in this but I have seen people doing it this way)

But, I am still struggling with the basic skeleton to get even the base up and running cos I find that there seems to be a tight coupling with the sample that downloaded from Spring site as in there is a validation maven plug in and if you added new entities then it is not going to run.  I spent yesterday night fixing that.

I hope you can let me have some clue if I am on the right direction in doing this project. Tks.

Also, later on I will be adding User log in function with session and really I am not sure how this piece fit together...it seems more like a MVC app to me...correct me if I am wrong...

/user/createWithList:
   post:
     tags:
     - "user"
     summary: "Creates list of users with given input array"
     description: ""
     operationId: "createUsersWithListInput"
     produces:
     - "application/xml"
     - "application/json"

/user/login:
   get:
     tags:
     - "user"
     summary: "Logs user into the system"
      operationId: "loginUser"
 
     parameters:
     - name: "username"
       in: "query"
       description: "The user name for login"
       required: true
       type: "string"
     - name: "password"
       in: "query"
       description: "The password for login in clear text"
       required: true
       type: "string"

And since it is written creates list of users with given input array I supposed this is a hardcoded function with List<User> add UserName blah blah blah

Hope to have your guidance Stephan and many thanks for your help.

[tangara goh]

Himai Minh wrote:You may find this tutorial helpful. You can create a repository class extending the CrudRepository .
https://www.concretepage.com/spring-5/spring-data-crudrepository-example

Hi Himai,

Just to clarify, using this would be not different from using Spring Boot right ?
Or I still have to use Spring Initizlizer to generate all the libraries that are needed before I try to use it in my case?

[Himai Minh]

Hi, Targara,
The CrudRepository can be used in Spring boot / Spring framework.
You can use Spring intializer to generate a Spring boot project and add some child classes for CrudRepository.

[tangara goh]

Himai Minh wrote:Hi, Targara,
The CrudRepository can be used in Spring boot / Spring framework.
You can use Spring intializer to generate a Spring boot project and add some child classes for CrudRepository.

Hi Himai Minh,

I would like to further check with you cos I found out that there is this petstore that has very similar end points like what I am doing now but they are using ResponseContext to return the response.

https://github.com/swagger-api/swagger-petstore/blob/master/src/main/java/io/swagger/petstore/controller/PetController.java

Is this the right way to do a RPC web app?

Can I use javax.ws.rs-api to do it ?

And if I don't do the testing like what they do using Petdata, do I just use a public void main (String []) and then I just create an instance of Pet and do a getId, getName like that is it ok ?

Furthermore, I'd like to clarify should I use the below code for /store/order

 @Transient
	private Set<Order> orders = new LinkedHashSet<>();

cos I am not sure about this one...since I can't tell if a user is supposed to be able to place an order just by looking at this description : /store/order and should I included Store as entity ?

Really, I am so confused really hope can get some help here....really I feel that maybe coding is not for me...

Tks.

[Himai Minh]

Hi,Tanagara,
The PetController is not using any Spring's Restful features.
I am sure javax.ws.rs-api is from JEE,not Spring
In Spring , you can use ResponseEntity<>  to return the output.

You may want to use these as reference:
https://spring.io/guides/tutorials/rest/
https://www.baeldung.com/spring-response-entity

[tangara goh]

Himai Minh wrote:Hi,Tanagara,
The PetController is not using any Spring's Restful features.
I am sure javax.ws.rs-api is from JEE,not Spring
In Spring , you can use ResponseEntity<>  to return the output.

You may want to use these as reference:
https://spring.io/guides/tutorials/rest/
https://www.baeldung.com/spring-response-entity

Thanks so much for the tutorial and I have used this guide and adapt accordingly.

But, another question came to my mind as I edit the PetController... cos for if I were to follow strictly the example in that swagger-petstore, I would just be getting a return in response as oppose to the traditional way of returning via GET, POST etc to return say an array of pets that has the same status for example.

I'd also want to clarify about java.ws.rs, cos in the utility of this petstore, they are also using import javax.ws.rs.core.MediaType so is it not advisable to use or it is ok to use?

Or ...I am sorry but I have problem in reading that swagger document...does it mean that I only need to return a response will do.  But then if it is just a response of ok or bad request, then what does this app serve the purpose then...so sorry but I really am not very good in this whole thing.

Thanks for your help in advance.

[Himai Minh]

Hi, Tangara,
For MediaType, you can use org.spring.framework.http.MediaType. There are different types in this class, such as APPLICATION_JSON, APPLICATION_ATOM_XML and etc.
If you choose to use Spring framework, then stick with it and don't need to use JEE for Restful.

If can return ResponseEntity with a status such as new ResponseEntity<>( message, HttpStatus.OK) or new ResposneEntity<>(message, HttpStatus.BAD_REQUEST) and etc.

[tangara goh]

Himai Minh wrote:Hi, Tangara,
For MediaType, you can use org.spring.framework.http.MediaType. There are different types in this class, such as APPLICATION_JSON, APPLICATION_ATOM_XML and etc.
If you choose to use Spring framework, then stick with it and don't need to use JEE for Restful.

If can return ResponseEntity with a status such as new ResponseEntity<>( message, HttpStatus.OK) or new ResposneEntity<>(message, HttpStatus.BAD_REQUEST) and etc.

Hi Himai,

That part is easy but the utility part if I were to use Spring HTTP headers I am afraid with my beginner level it is really tough to refactor.

I google abit and found this one at

https://stackoverflow.com/questions/62372402/spring-how-to-pass-automatically-https-header-between-microservices

Do you think this is the thing I should use or can you give me some hints how to refactor the utility part to accept json and xml using header request in Spring.
Tks.

[Himai Minh]

In Spring, your request is converted into Json by default.
You pass in a customized object type to a method, it will be converted into JSON by Spring.

[tangara goh]

Himai Minh wrote:In Spring, your request is converted into Json by default.
You pass in a customized object type to a method, it will be converted into JSON by Spring.

Thanks Himai,

Could you advise me at what stage people start to test out or do they test out Rest Controller at all ?  Or do I just use the RestClient as per your recommend article to do it.

I have often heard people using Postman or Curl or even Swagger to test out the end point so I just hope to have some advice where to start ?

Furthermore, I have tried using that sample app and modified accordingly to use Spring library as suggested by you.

However, there is this pets.add(createPet) that I can't get into the RespondEntity and Request Context, I hope you can let me know if there is a better way to do it other than using the PetData.

Thanks again for your help.

[tangara goh]

Himai Minh wrote:Hi, Tangara,
For MediaType, you can use org.spring.framework.http.MediaType. There are different types in this class, such as APPLICATION_JSON, APPLICATION_ATOM_XML and etc.
If you choose to use Spring framework, then stick with it and don't need to use JEE for Restful.

If can return ResponseEntity with a status such as new ResponseEntity<>( message, HttpStatus.OK) or new ResposneEntity<>(message, HttpStatus.BAD_REQUEST) and etc.

Hi Himai,

I need further clarification as  I noted that I am mixing RequestContext request in this ResponseEntity and I am not sure if it is alright to do that.  I just want to make sure that everything is correct, since you said don't sue JAX-RS.

Here'a a snippet of code

public ResponseEntity<PetData>deleteById(final RquestContext request, final Integer petId){
petdata.detlePetbyId(id) // so here the data will put a delete method with a fake id
if(petId == null){
throw new ResponseStatusException(HttpStatus.Bad_Request.Not_Found, "invalid ID supplied");
}
return new ResponseEntity<PetData>(petData, HttpStatus.OK);
}

You advice is greatly appreciate.