Home

[[TOC]]

Repository structure

    project-root/
    ├── skeleton-core/                  - Base module containing core functionality
    ├── skeleton-core-plus/             - Community Implementation code
    ├── skeleton-acceptance-test/       - Acceptance tests
    ├── devops/                         - DevOps deployment configurations and scripts
    ├── docs/                           - Project documentation
    │   └── api/                        - API documentation
    │       └── skeleton_openapi.yaml   - Open API specification
    ├── provider/                       - Cloud providers implementations root
    │   ├── aws/                        - Amazon Web Services implementation
    │   ├── azure/                      - Microsoft Azure implementation
    │   ├── ibm/                        - IBM implementation
    │   └── gcp/                        - Google Cloud Platform implementation
    ├── .mvn/                       - Maven wrapper directory
    ├── .gitlab/                        - GitLab integration
    ├── .sonarlint/                 - SonarLint integration
    ├── pom.xml                     - Maven configuration file (if using Maven)
    ├── .fossa.yml                  - license compliance
    └── README.md

Build & Configuration

Build System: Maven
Java Version: SDK 13
CI/CD: GitLab CI

Development Tools & Quality

Source Control:

Git version control (.gitignore, .gitattributes)
GitLab integration ( .gitlab/) 2. Code Quality:
SonarLint integration (.sonarlint/)
FOSSA for license compliance ( .fossa.yml)

DevOps & Deployment

Containerization support (Docker)
Multiple cloud provider support (AWS, Azure, Google Cloud, IBM)
Deployment scripts and configurations in the devops directory

Documentation

Main README file in the service root directory
Service documentation in docs/docs directory
Open API specification (skeleton_openapi.yaml)
Individual README files for different modules
License and legal notices (LICENSE, NOTICE files)

Sample CRUD API

This is an example of generic REST API, which demonstrates the RESTful design principles and provides examples of core OSDU services (Partition, Entitlements) integrations and common library usage (caching, feature-flags, common services clients).

Sample entity: {"id" : "1", "name" : "Foo"}

1. Get Samples Endpoint

Path: /samples
Method: GET
Produces: application/json
Purpose: Returns all available sample entities
Allowed roles: users.datalake.viewers or users.datalake.editors or users.datalake.admins

2. Get Sample Endpoint

Path: /samples/{sampleId}
Method: GET
Produces: application/json
Purpose: Returns sample entity by id
Allowed roles: users.datalake.viewers or users.datalake.editors or users.datalake.admins

3. Create Sample Endpoint

Path: /samples
Method: POST
Recieves: application/json
Purpose: Creates new sample entity
Allowed roles: users.datalake.editors or users.datalake.admins

4. Update Sample Endpoint

Path: /samples/{sampleId}
Method: PUT
Recieves: application/json
Purpose: Updates given sample entity
Allowed roles: users.datalake.editors or users.datalake.admins

5. Delete Sample Endpoint

Path: /samples/{sampleId}
Method: DELETE
Purpose: Deletes given sample entity
Allowed roles: users.datalake.editors or users.datalake.admins

Common API Endpoints

These endpoints are essential for: - Service health monitoring - Version tracking - Deployment validation - Infrastructure automation - Container orchestration - Service discovery

1. Info Endpoint

Path: /info
Method: GET
Produces: application/json
Purpose: Returns version and build information about the service
Security: N/A
Description: Version info endpoint that provides service details

2. Liveness Endpoint

Path: /liveness_check
Method: GET
Purpose: Used for health monitoring to determine if the service is alive
Use Case: Container health checks and service monitoring

3. Readiness Endpoint

Path: /readiness_check
Method: GET
Purpose: Used for health monitoring to determine if the service is ready to serve incoming requests
Use Case: Container health checks and service monitoring

Code organization recommendations

1. src/main/java/

Contains main source code
Classes organized in packages
Recommended to use domain package structure (e.g., com.company.project)

2. src/main/resources/

Project resources
Configuration files
Properties files
Logging configurations

3. src/test/

Test classes
Structure mirrors main/
Unit tests
Integration tests

4. Package structure:

    org.opengroup.osdu/
    ├── api/             - API interfaces
    ├── config/        - Configuration classes
    ├── controller/    - Controllers (for web applications)
    ├── model/         - Data models
    ├── repository/    - Database interaction classes
    ├── service/       - Business logic
    └── util/          - Helper classes

5. Naming conventions:

Use meaningful package and class names
Follow Java naming conventions
CamelCase for classes (MyClass)
camelCase for methods and variables (myMethod)

6. Documentation:

README.md in project root
Javadoc for public classes and methods
Comments for complex logic

7. Dependencies:

Managed through pom.xml
Clear separation between production and test dependencies

8. Resources:

application.properties/yaml for configuration
Separate properties files for different environments
Logical grouping of resources in folders

Conclusion

This structure provides: - Clear code organization - Easy maintenance - Scalability - Clean OSDU architecture principles - Build automation convenience