Skip to content

F1 (Java) Story 6: Implement /v1/projects CRUD API for collaboration projects

Description

Implement and set up the "/projects" endpoint of the REST API for CRUD operations pertaining to the "Collaboration Project" business domain entity per the CollaborationProject.1.0.0.json schema provided by the OSDU data definition committee.

The endpoint serves as the first primary business endpoint of the service, setting a model for future endpoints. For initial implementation, the methods provided under this endpoint should be backed by mock data. Implement the following RESTful methods for this endpoint:

GET /projects/{project_id}

Retrieves a specific project by recordID

  • Returns: a single CollaborationProject record

GET /projects

Retrieves all available CollaborationProjects

  • Returns: a JSON-array of all available projects' recordIDs

POST /projects

Creates a new collaboration project.

  • Payload: A JSON object constrained by the CollaborationProject schema with some restrictions:
    • "data.WIPResources[]" node must not present
    • "data.LifecycleEvents[]" node must not present
  • Returns: a single CollaborationProject record

A crucial requirement for this project is the auto-generation of OpenAPI documentation using the Springfox library. The APIs need to be annotated correctly for this purpose.

Acceptance Criteria

  • The "/projects" endpoint is implemented and is functioning with all methods.
  • The endpoint effectively supports Create and Read operations for the "Collaboration Project" entity, with results derived from mock data.
  • The endpoint structuring and implementation serve as a robust model for future endpoint development.
  • The "/projects" endpoint methods align with the CollaborationProject.1.0.0.json schema.
  • OpenAPI documentation is automatically generated and accurately represents the API endpoints, requests, and responses as per the examples given in Technical Notes section.

Testing Scenarios

  • Verify the functionality of each method (GET, POST) on the "/projects" endpoint, confirming responses match with the mock-up data outcomes.
  • Validate that data sent and received by the endpoint methods is compliant with the CollaborationProject.1.0.0.json schema.
  • Conduct stress testing to assess scalability and efficiency of the endpoint.

Technical Notes

  • Maintain adherence to RESTful principles and best practices during endpoint creation.
  • Represent realistic data structures and responses in the mock data.
  • Formulate the endpoint in line with existing OSDU core services' endpoints for consistency.
  • Use "os-core-common" and "os-core-lib-aws" libraries aligning with how other OSDU core services use them to reduce boilerplate code.
  • Example 1: Demonstrates enabling feature and method-wide API documentation
@Configuration
public class SwaggerConfig {

   @Bean
   public Docket api() {
      return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build()
        .apiInfo(apiInfo());
    }

   private ApiInfo apiInfo() {
      return new ApiInfo(
         "My REST API", 
         "Some custom description of the API.", 
         "API TOS", 
         "Terms of service", 
         new Contact("John Doe", "www.example.com", "myeaddress@company.com"), 
         "License of API", "API license URL", Collections.emptyList()
      );
   }
}

@Controller
public class ProductController {
   
   @ApiOperation(value = "View a list of available products", response = Iterable.class)
   @ApiResponses(value = {
      @ApiResponse(code = 200, message = "Successfully retrieved list"),
      @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
      @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
      @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
   }
   @GetMapping("/products")
   public Iterable<Product> list() {
      return productService.listAllProducts();
   }
}
'[{"op":"replace", "path":"/fieldName", "value":"newValue"}]'
Edited by Rostislav Dublin (EPAM)