Package org.apache.archiva.redback.rest.api.services.v2

This is the V2 REST API of Redback. It uses JAX-RS annotations for defining the endpoints. The API is documented with OpenApi annotations.

Some design principles of the API and classes:

  • All services use V2 model classes. Internal models are always converted to V2 classes.
  • Schema attributes use the snake case syntax (lower case with '_' as divider)
  • Return code 200 and 201 (POST) is used for successful execution.
  • Return code 403 is used, if the user has not the permission for the action.
  • Return code 422 is used for input that has invalid data.

Querying entity lists

The main entities of a given path are retrieved on the base path. Further sub entities or entries may be retrieved via subpaths. A single entity is returned by the "{id}" path. Be careful with technical paths that are parallel to the id path. Avoid naming conflicts with the id and technical paths. Entity attributes may be retrieved by "{id}/{attribute}" path or if there are lists or collections by "{id}/mycollection/{subentryid}"

  • GET method is used for retrieving entities on the base path ""
  • The query for base entities should always return a paged result and be filterable and sortable
  • Query parameters for filtering, ordering and limits should be optional and proper defaults must be set
  • Return code 200 is used for successful retrieval
  • This action is idempotent

Querying single entities

Single entities are retrieved on the path "{id}"

  • GET method is used for retrieving a single entity. The id is always a path parameter.
  • Return code 200 is used for successful retrieval
  • Return code 404 is used if the entity with the given id does not exist
  • This action is idempotent

Creating entities

The main entities are created on the base path "".

  • POST is used for creating new entities
  • The POST body must always have a complete definition of the entity.
  • A unique id or name attribute is required for entities. If the id is generated during POST, it must be returned by response body.
  • A successful POST request should always return the entity definition as it would be returned by the GET request.
  • Return code 201 is used for successful creation of the new entity.
  • A successful response has a Location header with the URL for retrieving the single created entity.
  • Return code 303 is used, if the entity exists already
  • This action is not idempotent

Updating entities

The path for entity update must contain the '{id}' of the entity. The path should be the same as for the GET operation.

  • PUT is used for updating existing entities
  • The body contains a JSON object. Only existing attributes are updated.
  • A successful PUT request should return the complete entity definition as it would be returned by the GET request.
  • Return code 200 is used for successful update of the new entity. Even if nothing changed.
  • This action is idempotent

Deleting entities

The path for entity deletion must contain the '{id}' of the entity. The path should be the same as for the GET operation.

  • DELETE is used for deleting existing entities
  • The successful operation has no request and no response body
  • Return code 200 is used for successful deletion of the new entity.
  • This action is not idempotent

Errors

  • A error uses a return code >=400
  • All errors use the same result object (org.apache.archiva.rest.api.services.v2.ArchivaRestError
  • Error messages are returned as keys. Translation is part of the client application.
Since:
3.0
Author:
Martin Stockhammer