Apicurio Groups API
The Groups API from Apicurio — 3 operation(s) for groups.
OpenAPI Specification
openapi: 3.1.0
info:
title: Apicurio Registry Admin Groups API
version: 3.1.x
description: Apicurio Registry is a high-performance, runtime registry for schemas and API designs. It stores and manages OpenAPI, AsyncAPI, Avro, JSON Schema, Protobuf, and other artifact types, providing a REST API for schema management with compatibility checking and content versioning.
contact:
name: Apicurio
url: https://www.apicur.io/
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:8080/apis/registry/v3
description: Local Apicurio Registry
tags:
- name: Groups
paths:
/groups:
summary: Collection of the groups in the registry.
get:
tags:
- Groups
parameters:
- name: limit
description: The number of groups to return. Defaults to 20.
schema:
type: integer
in: query
- name: offset
description: The number of groups to skip before starting the result set. Defaults to 0.
schema:
type: integer
in: query
- name: order
description: Sort order, ascending (`asc`) or descending (`desc`).
schema:
$ref: '#/components/schemas/SortOrder'
in: query
- name: orderby
description: 'The field to sort by. Can be one of:
* `name`
* `createdOn`
'
schema:
$ref: '#/components/schemas/GroupSortBy'
in: query
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GroupSearchResults'
description: On a successful response, returns a bounded set of groups.
'500':
$ref: '#/components/responses/ServerError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: listGroups
summary: List groups
description: Returns a list of all groups. This list is paged.
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGroup'
required: true
tags:
- Groups
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GroupMetaData'
description: The group has been successfully created.
'400':
$ref: '#/components/responses/BadRequest'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/ServerError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: createGroup
summary: Create a new group
description: 'Creates a new group.
This operation can fail for the following reasons:
* A server error occurred (HTTP error `500`)
* The group already exist (HTTP error `409`)
* Invalid group ID (e.g., reserved name ''default'') (HTTP error `400`)
'
/groups/{groupId}:
summary: Collection to manage a single group in the registry.
parameters:
- name: groupId
description: The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.
schema:
$ref: '#/components/schemas/GroupId'
in: path
required: true
get:
tags:
- Groups
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GroupMetaData'
description: The group's metadata.
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: getGroupById
summary: Get a group by the specified ID.
description: 'Returns a group using the specified id.
This operation can fail for the following reasons:
* No group exists with the specified ID (HTTP error `404`)
* A server error occurred (HTTP error `500`)'
put:
requestBody:
description: The new group metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/EditableGroupMetaData'
required: true
tags:
- Groups
responses:
'204':
description: Empty response when the metadata is successfully updated.
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: updateGroupById
summary: Update group metadata
description: 'Updates the metadata of a group using the specified id.
This operation can fail for the following reasons:
* No group exists with the specified ID (HTTP error `404`)
* A server error occurred (HTTP error `500`)'
delete:
tags:
- Groups
responses:
'204':
description: Empty content indicates a successful deletion.
'404':
$ref: '#/components/responses/NotFound'
'405':
$ref: '#/components/responses/MethodNotAllowed'
'500':
$ref: '#/components/responses/ServerError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: deleteGroupById
summary: Delete a group by the specified ID.
description: 'Deletes a group by identifier. This operation also deletes all artifacts within
the group, so should be used very carefully.
This operation can fail for the following reasons:
* A server error occurred (HTTP error `500`)
* The group does not exist (HTTP error `404`)
'
/search/groups:
summary: Search for groups in the registry.
get:
tags:
- Groups
parameters:
- name: offset
description: The number of artifacts to skip before starting to collect the result set. Defaults to 0.
schema:
default: 0
type: integer
in: query
required: false
- name: limit
description: The number of artifacts to return. Defaults to 20.
schema:
default: 20
type: integer
in: query
required: false
- name: order
description: Sort order, ascending (`asc`) or descending (`desc`).
schema:
$ref: '#/components/schemas/SortOrder'
in: query
- name: orderby
description: 'The field to sort by. Can be one of:
* `name`
* `createdOn`
'
schema:
$ref: '#/components/schemas/GroupSortBy'
in: query
- name: labels
description: 'Filter by one or more name/value label. Separate each name/value pair using a colon. For
example `labels=foo:bar` will return only artifacts with a label named `foo`
and value `bar`.'
schema:
type: array
items:
type: string
in: query
- name: description
description: Filter by description.
schema:
type: string
in: query
- name: groupId
description: Filter by group name.
schema:
type: string
in: query
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GroupSearchResults'
description: 'On a successful response, returns a result set of groups - one for each group
in the registry that matches the criteria.'
'500':
$ref: '#/components/responses/ServerError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: searchGroups
summary: Search for groups
description: 'Returns a paginated list of all groups that match the provided filter criteria.
This operation can fail for the following reasons:
* A server error occurred (HTTP error `500`)
'
components:
schemas:
SortOrder:
description: ''
enum:
- asc
- desc
type: string
EditableGroupMetaData:
title: Root Type for EditableGroupMetaData
description: ''
type: object
properties:
description:
type: string
labels:
$ref: '#/components/schemas/Labels'
description: ''
owner:
description: ''
type: string
example:
description: The description of the group.
owner: user-1
labels:
custom-1: foo
custom-2: bar
GroupId:
description: An ID of a single artifact group.
pattern: ^.{1,512}$
type: string
example: '"my-group"'
ProblemDetails:
title: Root Type for Error
description: 'All error responses, whether `4xx` or `5xx` will include one of these as the response
body.'
required:
- title
- status
type: object
properties:
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
type:
description: A URI reference [RFC3986] that identifies the problem type.
type: string
title:
description: A short, human-readable summary of the problem type.
type: string
status:
format: int32
description: The HTTP status code.
type: integer
instance:
description: A URI reference that identifies the specific occurrence of the problem.
type: string
name:
description: The name of the error (typically a server exception class name).
type: string
example:
status: 500
name: NullPointerException
title: An error occurred somewhere.
GroupMetaData:
title: Root Type for GroupMetaData
description: ''
required:
- groupId
- owner
- createdOn
- modifiedBy
- modifiedOn
type: object
properties:
description:
type: string
owner:
type: string
createdOn:
format: date-time
type: string
modifiedBy:
type: string
modifiedOn:
format: date-time
type: string
labels:
$ref: '#/components/schemas/Labels'
description: ''
groupId:
$ref: '#/components/schemas/GroupId'
description: ''
example:
groupId: group-identifier
description: Description of the group
artifactsType: AVRO
owner: user1
createdOn: '2019-03-22T12:51:19Z'
modifiedBy: user2
modifiedOn: '2019-07-19T15:09:00Z'
properties:
custom-1: foo
custom-2: bar
SearchedGroup:
description: Models a single group from the result set returned when searching for groups.
required:
- owner
- createdOn
- groupId
- modifiedBy
- modifiedOn
type: object
properties:
description:
description: ''
type: string
createdOn:
format: date-time
description: ''
type: string
owner:
description: ''
type: string
modifiedOn:
format: date-time
description: ''
type: string
modifiedBy:
description: ''
type: string
groupId:
$ref: '#/components/schemas/GroupId'
description: ''
labels:
$ref: '#/components/schemas/Labels'
description: ''
example:
groupId: My-Group
name: Group Name
description: Description of the group
owner: user1
createdOn: '2019-03-22T12:51:19Z'
modifiedBy: user1
modifiedOn: '2019-03-22T12:51:19Z'
GroupSortBy:
description: ''
enum:
- groupId
- createdOn
- modifiedOn
type: string
GroupSearchResults:
description: Describes the response received when searching for groups.
required:
- count
- groups
type: object
properties:
groups:
description: The groups returned in the result set.
type: array
items:
$ref: '#/components/schemas/SearchedGroup'
count:
description: "The total number of groups that matched the query that produced the result set (may be \nmore than the number of groups in the result set)."
type: integer
Labels:
description: User-defined name-value pairs. Name and value must be strings.
type: object
additionalProperties:
type: string
x-codegen-inline: true
x-codegen-type: StringMap
CreateGroup:
title: Root Type for CreateGroupMetaData
description: ''
required:
- groupId
type: object
properties:
description:
type: string
labels:
$ref: '#/components/schemas/Labels'
description: ''
groupId:
$ref: '#/components/schemas/GroupId'
description: ''
example:
groupId: group-identifier
description: The description of the artifact.
labels:
custom-1: foo
custom-2: bar
responses:
ServerError:
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
ErrorExample:
value:
error_code: 500
message: Lost connection to the database.
description: Common response for all operations that can fail with an unexpected server error.
BadRequest:
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
description: Common response for all operations that can return a `400` error.
Unauthorized:
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
UnauthorizedExample:
value:
detail: 'UnauthorizedException: User is not authenticated.'
title: User is not authenticated.
status: 401
name: UnauthorizedException
description: Common response for all operations that can return a `401` error indicating authentication is required.
Conflict:
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
ConflictExample:
value:
error_code: 409
message: The artifact content was invalid.
description: Common response used when an input conflicts with existing data.
NotFound:
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
NotFoundExample:
value:
error_code: 404
message: No artifact with id 'Topic-1/Inbound' could be found.
description: Common response for all operations that can return a `404` error.
Forbidden:
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
ForbiddenExample:
value:
detail: 'ForbiddenException: User is not authorized to perform this operation.'
title: User is not authorized to perform this operation.
status: 403
name: ForbiddenException
description: Common response for all operations that can return a `403` error indicating the user is authenticated but not authorized.
MethodNotAllowed:
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
MethodNotAllowedExample:
value:
error_code: 405
message: Method is currently not supported or disabled.
description: Common response for all operations that can fail due to method not allowed or disabled.
securitySchemes:
BasicAuth:
type: http
scheme: basic
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://example.com/realms/apicurio/protocol/openid-connect/token
scopes:
read: Read access
write: Write access
admin: Admin access
x-codegen:
suppress-date-time-formatting: true
bean-annotations:
- io.quarkus.runtime.annotations.RegisterForReflection
- annotation: lombok.experimental.SuperBuilder
excludeEnums: true
- annotation: lombok.AllArgsConstructor
excludeEnums: true
- annotation: lombok.NoArgsConstructor
excludeEnums: true
- annotation: lombok.EqualsAndHashCode
excludeEnums: true
- annotation: lombok.ToString(callSuper = true)
excludeEnums: true