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
and201
(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
orname
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
-
Interface Summary Interface Description AuthenticationService Authentication serviceGroupService RoleService Service interface for role management.UserService Service interface for user management