Skip to content

API_ENDPOINTS.md

Latest commit

 

History

History
169 lines (139 loc) · 11.9 KB

API_ENDPOINTS.md

File metadata and controls

169 lines (139 loc) · 11.9 KB

API Endpoints

This service is a Spring Boot JSON schema store. The configured Spring Data REST base path is:

/api/v2

Authentication and authorization below are derived from SecurityConfig.java.

Auth Legend

Auth Meaning
Public Explicitly allowed without authentication.
Authenticated Requires a valid authenticated principal.
editor Requires authenticated user with editor authority.
admin Requires authenticated user with admin authority.

Custom Controller APIs

Method Endpoint Auth What it does
GET / Public Redirects to the API root, /api/v2.
GET /api/v2 Public Spring Data REST API root.
GET /api/v2/me Authenticated Returns the current authenticated user.
GET /api/v2/schemas?id={schemaId} Authenticated Gets a schema by full schema ID.
GET /api/v2/schemas/{accession}/{version} Authenticated Gets a schema by accession and version.
GET /api/v2/schemas/search?text={text}&page={page}&size={size} Authenticated Searches schemas with optional text and pagination.
GET /api/v2/schemas/list?page={page}&size={size} Public Returns a paged summary list of schemas.
GET /api/v2/schemas/list/versions/{accession} Authenticated Lists versions for a schema accession.
POST /api/v2/schemas Authenticated Creates a schema through the custom schema controller.
PUT /api/v2/schemas?id={schemaId} Authenticated Updates a schema through the custom schema controller.
DELETE /api/v2/schemas?id={schemaId} Authenticated Deletes a schema through the custom schema controller.
GET /api/v2/schemas/search/findByExample?... Public Finds schemas by example fields, with pageable parameters.
GET /api/v2/schemas/search/findAttributeValues?attributeName={name} Authenticated Returns distinct values for a schema attribute.
GET /api/v2/fields/search/findByExample?... Public Finds fields by example fields, with pageable parameters.
GET /api/v2/fields/search/findAttributeValues?attributeName={name} Public Returns distinct values for a field attribute.
GET /api/v2/fieldGroups/search/findByExample?... Public Finds field groups by example fields, with pageable parameters.
GET /api/v2/metaSchemas?id={schemaId} Authenticated Gets a metaschema by ID.
GET /api/v2/metaSchemas/search?page={page}&size={size} Authenticated Returns a paged metaschema list.
POST /api/v2/metaSchemas Authenticated Creates a metaschema.
GET /registry/schemas/{accessionOrId} Public Returns the latest plain JSON Schema by accession or ID.
GET /registry/schemas/{accession}/{version} Public Returns a versioned plain JSON Schema by accession and version.
GET /registry/schemas?id={schemaId} Public Dynamically generates plain JSON Schema from checklist fields.
GET /checklist/converter/{checklist} editor Converts an ENA checklist to JSON schema without saving.
PUT /checklist/converter/{checklist} Authenticated Converts and saves an ENA checklist. Note: security only explicitly applies editor to GET /checklist/converter/**; this PUT falls through to authenticated.
GET /checklist/converter/convert/all editor Imports the BioSamples schema and persists all ENA checklists.
GET /checklist/converter/convert/biosamples editor Imports BioSamples checklists from the bundled file.

Spring Data REST Repository APIs

These endpoints are generated by Spring Data REST from repository interfaces. Collection endpoints generally support pagination parameters such as page, size, and sort.

Schema Metadata: /api/v2/mongoJsonSchemas

Backed by SchemaRepository and the MongoJsonSchema document.

Method Endpoint Auth What it does
GET /api/v2/mongoJsonSchemas Public Lists schema metadata records.
GET /api/v2/mongoJsonSchemas/{id} Public Gets one schema metadata record.
POST /api/v2/mongoJsonSchemas editor Creates a schema metadata record.
PUT /api/v2/mongoJsonSchemas/{id} editor Replaces a schema metadata record.
PATCH /api/v2/mongoJsonSchemas/{id} Authenticated Partially updates a schema metadata record. Note: security explicitly protects POST, PUT, and DELETE; PATCH falls through to authenticated.
DELETE /api/v2/mongoJsonSchemas/{id} editor Deletes a schema metadata record.
GET /api/v2/mongoJsonSchemas/search/findAllByText?text={text} Public Full-text schema metadata search.
GET /api/v2/mongoJsonSchemas/search/findAllByTextPartial?text={text} Public Partial text schema metadata search.
GET /api/v2/mongoJsonSchemas/search/findByIdIn?ids={ids} Public Finds schemas by IDs.
GET /api/v2/mongoJsonSchemas/search/findByNameOrderByVersionDesc?schemaName={name} Public Finds schemas by name, newest versions first.
GET /api/v2/mongoJsonSchemas/search/findByAccessionOrderByVersionDesc?accession={accession} Public Finds schemas by accession, newest versions first.
GET /api/v2/mongoJsonSchemas/search/findFirstByNameOrderByVersionDesc?schemaName={name} Public Finds the latest schema by name.
GET /api/v2/mongoJsonSchemas/search/findFirstByNameAndVersionOrderByVersionDesc?schemaName={name}&version={version} Public Finds schema by name and version.
GET /api/v2/mongoJsonSchemas/search/findFirstByOrderByAccessionDesc Public Finds the highest accession record.
GET /api/v2/mongoJsonSchemas/search/findFirstByAuthorityOrderByAccessionDesc?authority={authority} Public Finds the highest accession for an authority.
GET /api/v2/mongoJsonSchemas/search/findFirstByAccessionAndVersionOrderByVersionDesc?accession={accession}&version={version} Public Finds schema by accession and version.
GET /api/v2/mongoJsonSchemas/search/findFirstByAccessionOrderByVersionDesc?accession={accession} Public Finds the latest schema by accession.
GET /api/v2/mongoJsonSchemas/search/findFirstByDomainAndNameOrderByVersionDesc?domain={domain}&name={name} Public Finds the latest schema by domain and name.

Fields: /api/v2/fields

Backed by FieldRepository and the Field document.

Method Endpoint Auth What it does
GET /api/v2/fields Public Lists checklist fields.
GET /api/v2/fields/{id} Public Gets one checklist field.
POST /api/v2/fields editor Creates a field.
PUT /api/v2/fields/{id} editor Replaces a field.
PATCH /api/v2/fields/{id} Authenticated Partially updates a field. Note: security explicitly protects POST, PUT, and DELETE; PATCH falls through to authenticated.
DELETE /api/v2/fields/{id} editor Deletes a field.
GET /api/v2/fields/search/findByLabel?label={label} Public Finds a field by label.
GET /api/v2/fields/search/findByUsedBySchemas?schemaId={nameVersion} Public Finds fields used by a schema.
GET /api/v2/fields/search/findAllByIdIn?ids={ids} Public Finds fields by IDs.
GET /api/v2/fields/search/findAllByNameIn?names={names} Public Finds fields by names.
GET /api/v2/fields/search/findAllByText?text={text} Public Full-text field search.
GET /api/v2/fields/search/findAllByTextPartial?text={text} Public Partial text field search.
GET /api/v2/fields/search/findByName?name={name} Public Finds a field by name.

Field Groups: /api/v2/fieldGroups

Backed by FieldGroupRepository and the FieldGroup document.

Method Endpoint Auth What it does
GET /api/v2/fieldGroups Public Lists field groups.
GET /api/v2/fieldGroups/{id} Public Gets one field group.
POST /api/v2/fieldGroups Authenticated Creates a field group.
PUT /api/v2/fieldGroups/{id} Authenticated Replaces a field group.
PATCH /api/v2/fieldGroups/{id} Authenticated Partially updates a field group.
DELETE /api/v2/fieldGroups/{id} Authenticated Deletes a field group.
GET /api/v2/fieldGroups/search/findByName?name={name} Public Finds a field group by name.
GET /api/v2/fieldGroups/search/findAllByIdIn?ids={ids} Public Finds field groups by IDs.
GET /api/v2/fieldGroups/search/findAllByTextPartial?text={text} Public Partial text field group search.

Users: /api/v2/users

Backed by UserRepository.

Method Endpoint Auth What it does
GET /api/v2/users admin Lists users.
GET /api/v2/users/{id} admin Gets one user.
POST /api/v2/users admin Creates a user.
PUT /api/v2/users/{id} admin Replaces a user.
PATCH /api/v2/users/{id} Authenticated Partially updates a user. Note: security explicitly protects GET, POST, and PUT; PATCH falls through to authenticated.
DELETE /api/v2/users/{id} Authenticated Deletes a user. Note: security does not explicitly protect DELETE /api/v2/users/**, so it falls through to authenticated.
GET /api/v2/users/search/me Authenticated Returns the current authenticated user via repository search resource.
GET /api/v2/users/search/findByUsername?username={username} admin Finds a user by username.

Mongo Metaschemas: /api/v2/mongoMetaSchemas

Backed by MetaSchemaRepository and the MongoMetaSchema document. The repository has no explicit @RepositoryRestResource path, so the generated path should be confirmed with /actuator/mappings at runtime.

Method Endpoint Auth What it does
GET /api/v2/mongoMetaSchemas Authenticated Lists Mongo metaschema records.
GET /api/v2/mongoMetaSchemas/{id} Authenticated Gets one Mongo metaschema record.
POST /api/v2/mongoMetaSchemas Authenticated Creates a Mongo metaschema record.
PUT /api/v2/mongoMetaSchemas/{id} Authenticated Replaces a Mongo metaschema record.
PATCH /api/v2/mongoMetaSchemas/{id} Authenticated Partially updates a Mongo metaschema record.
DELETE /api/v2/mongoMetaSchemas/{id} Authenticated Deletes a Mongo metaschema record.
GET /api/v2/mongoMetaSchemas/search/findByNameOrderByVersionDesc?schemaName={name} Authenticated Finds metaschemas by name, newest versions first.
GET /api/v2/mongoMetaSchemas/search/findFirstByNameOrderByVersionDesc?schemaName={name} Authenticated Finds the latest metaschema by name.
GET /api/v2/mongoMetaSchemas/search/findFirstByNameAndVersionOrderByVersionDesc?schemaName={name}&version={version} Authenticated Finds metaschema by name and version.

Actuator APIs

Actuator is configured with:

management:
  endpoints:
    web:
      exposure:
        include: "*"
Method Endpoint Auth What it does
GET /actuator/** Public Exposes all configured Spring Boot Actuator endpoints.
GET /actuator/mappings Public Shows runtime request mappings; use this to confirm generated Spring Data REST endpoints.

Notes

  • README.md lists the main consumer-facing endpoints used by checklist-editor and BioSamples.
  • api/schema-store-api.yaml only documents /api/v2/schemas/search, so it is not a complete API catalogue.
  • Spring Data REST generated endpoint names and query parameter names should be verified at runtime with GET /actuator/mappings, especially for repositories without explicit @RepositoryRestResource(path = ...).
  • Some security rules only constrain selected HTTP methods. Where PATCH or DELETE are not explicitly matched, they fall through to .anyRequest().authenticated().