Skip to content

Commit 719f169

Browse files
n1ru4ln1ru4l
authored
docs: public graphql api documentation (#6811)
1 parent 27089f0 commit 719f169

File tree

9 files changed

+1029
-2
lines changed

9 files changed

+1029
-2
lines changed

‎packages/services/api/src/modules/organization/module.graphql.ts

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,9 @@ export default gql`
3636
answerOrganizationTransferRequest(
3737
input: AnswerOrganizationTransferRequestInput!
3838
): AnswerOrganizationTransferRequestResult!
39+
"""
40+
Create a new member role with permissions.
41+
"""
3942
createMemberRole(input: CreateMemberRoleInput! @tag(name: "public")): CreateMemberRoleResult!
4043
@tag(name: "public")
4144
updateMemberRole(input: UpdateMemberRoleInput! @tag(name: "public")): UpdateMemberRoleResult!
@@ -58,10 +61,27 @@ export default gql`
5861
}
5962
6063
input CreateOrganizationAccessTokenInput {
64+
"""
65+
Organization in which the access token should be created.
66+
"""
6167
organization: OrganizationReferenceInput! @tag(name: "public")
68+
"""
69+
Title of the access token.
70+
"""
6271
title: String! @tag(name: "public")
72+
"""
73+
Additional description containing information about the purpose of the access token.
74+
"""
6375
description: String @tag(name: "public")
76+
"""
77+
List of permissions that are assigned to the access token.
78+
A list of available permissions can be retrieved via the \`Organization.availableOrganizationAccessTokenPermissionGroups\` field.
79+
"""
6480
permissions: [String!]! @tag(name: "public")
81+
"""
82+
Resources on which the permissions should be granted (project, target, service, and app deployments).
83+
Permissions are inherited by sub-resources.
84+
"""
6585
resources: ResourceAssignmentInput! @tag(name: "public")
6686
}
6787
@@ -102,6 +122,9 @@ export default gql`
102122
}
103123
104124
input DeleteOrganizationAccessTokenInput {
125+
"""
126+
The access token that should be deleted.
127+
"""
105128
organizationAccessToken: OrganizationAccessTokenReference! @tag(name: "public")
106129
}
107130
@@ -394,12 +417,12 @@ export default gql`
394417
395418
type OrganizationInvitationEdge {
396419
node: OrganizationInvitation! @tag(name: "public")
397-
cursor: String!
420+
cursor: String! @tag(name: "public")
398421
}
399422
400423
type OrganizationInvitationConnection {
401424
edges: [OrganizationInvitationEdge!]! @tag(name: "public")
402-
pageInfo: PageInfo!
425+
pageInfo: PageInfo! @tag(name: "public")
403426
}
404427
405428
type OrganizationInvitation {
@@ -485,9 +508,21 @@ export default gql`
485508
}
486509
487510
input CreateMemberRoleInput {
511+
"""
512+
The organization in which the member role should be created.
513+
"""
488514
organization: OrganizationReferenceInput! @tag(name: "public")
515+
"""
516+
The name of the member role (must be unique).
517+
"""
489518
name: String! @tag(name: "public")
519+
"""
520+
A description describing the purpose of the member role.
521+
"""
490522
description: String! @tag(name: "public")
523+
"""
524+
A list of available permissions can be retrieved via the \`Organization.availableMemberPermissionGroups\` field.
525+
"""
491526
selectedPermissions: [String!]! @tag(name: "public")
492527
}
493528

‎packages/web/docs/src/content/_meta.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ export default {
99
'other-integrations': 'Other Integrations',
1010
'api-reference': 'CLI/API Reference',
1111
specs: 'Specifications',
12+
'graphql-api': 'GraphQL API',
1213
'use-cases': 'Use Cases',
1314
'migration-guides': 'Migration Guides',
1415
'self-hosting': 'Self-Hosting',

‎packages/web/docs/src/content/graphql-api/_meta.ts

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
export default {
2+
index: 'Using the GraphQL API',
3+
'member-management': 'Manage Members',
4+
'access-token-management': 'Manage Access Tokens',
5+
'project-management': 'Manage Projects',
6+
'target-management': 'Manage Targets',
7+
'contract-management': 'Manage Contracts',
8+
};

‎packages/web/docs/src/content/graphql-api/access-token-management.mdx

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
title: Access Token Management via the GraphQL API
3+
description: Learn how to manage access tokens via the Hive Console GraphQL API.
4+
---
5+
6+
# Access Token Management via the GraphQL API
7+
8+
Manage access tokens used for schema publishing, schema checks, app deployment publishes and other
9+
actions available via the GraphQL API. For more information, please refer to our
10+
[access token documentation](/docs/management/access-tokens).
11+
12+
## Retrieve a List of Access Tokens
13+
14+
Use the `Organization.accessTokens` field for retrieving a paginated list of available access.
15+
16+
```graphql filename="Example: Paginated list of access tokens"
17+
query OrganizationAccessTokens($organizationSlug: String!, $after: String) {
18+
organization(reference: { bySelector: { organizationSlug: $organizationSlug } }) {
19+
accessTokens(first: 10, after: $after) {
20+
edges {
21+
node {
22+
id
23+
title
24+
description
25+
createdAt
26+
}
27+
}
28+
pageInfo {
29+
endCursor
30+
hasNextPage
31+
}
32+
}
33+
}
34+
}
35+
```
36+
37+
## Retrieve a Single Access Token
38+
39+
Instead of fetching a paginated list, it is also possible to retrieve a single access token by its
40+
id via the `Organization.accessToken` field.
41+
42+
```graphql filename="Example: Retrieve access token by id"
43+
query OrganizationAccessTokenById($organizationSlug: String!, $accessTokenId: ID!) {
44+
organization(reference: { bySelector: { organizationSlug: $organizationSlug } }) {
45+
accessToken(id: $accessTokenId) {
46+
id
47+
title
48+
description
49+
createdAt
50+
}
51+
}
52+
}
53+
```
54+
55+
## Retrieve a List of Permissions Assignable to Access Tokens
56+
57+
A list of permissions that are assignable to access tokens can be retrieved via the
58+
`Organization.availableOrganizationAccessTokenPermissionGroups` field. It returns a list of all
59+
permission groups and their permissions.
60+
61+
```graphql filename="Example: Retrieve permissions by group"
62+
query OrganizationPermissions($organizationSlug: String!) {
63+
organization(reference: { bySelector: { organizationSlug: $organizationSlug } }) {
64+
id
65+
slug
66+
availableOrganizationAccessTokenPermissionGroups {
67+
id
68+
permissions {
69+
id
70+
title
71+
description
72+
}
73+
}
74+
}
75+
}
76+
```
77+
78+
## Create an Access Token
79+
80+
An access token can be created by using the `Mutation.createOrganizationAccessToken` field.
81+
82+
The `CreateOrganizationAccessTokenResultOk.privateAccessKey` field in the mutation results contains
83+
the access key that can be used with the Hive CLI or the Hive GraphQL API as an authorization
84+
header.
85+
86+
```graphql filename="Example: Create an Access Token"
87+
mutation CreateAccessTokenMutation($input: CreateOrganizationAccessTokenInput!) {
88+
createOrganizationAccessToken(input: $input) {
89+
ok {
90+
privateAccessKey
91+
}
92+
error {
93+
message
94+
details {
95+
title
96+
description
97+
}
98+
}
99+
}
100+
}
101+
```
102+
103+
### Resource Assignment
104+
105+
Use the `CreateOrganizationAccessTokenInput.resources` field to specify on which resources the
106+
permissions should apply. Permissions are inherited by all subresources (organization, project,
107+
target, service, app deployment).
108+
109+
```json5 filename="Example: Grant permissions on all resources"
110+
{
111+
mode: 'ALL',
112+
projects: []
113+
}
114+
```
115+
116+
```json5 filename="Example: Grant permissions on specific project"
117+
{
118+
mode: 'GRANULAR',
119+
projects: [
120+
{
121+
projectId: '<PROJECT_ID>',
122+
targets: {
123+
// Grant permissions on all targets within project
124+
mode: 'ALL'
125+
}
126+
}
127+
]
128+
}
129+
```
130+
131+
```json5 filename="Example: Grant permissions on specific target"
132+
{
133+
mode: 'GRANULAR',
134+
projects: [
135+
{
136+
projectId: '<PROJECT_ID>',
137+
targets: {
138+
// Grant permissions on a single targets within project
139+
mode: 'GRANULAR',
140+
targets: [
141+
{
142+
targetId: '<TARGET_ID>',
143+
// Grant permissions on a all services within target
144+
services: { mode: 'ALL' },
145+
// Grant permissions on a all app deployments within target
146+
appDeployments: { mode: 'ALL' }
147+
}
148+
]
149+
}
150+
}
151+
]
152+
}
153+
```
154+
155+
## Delete an Access Token
156+
157+
A access token can be deleted by using the `Mutation.deleteOrganizationAccessToken` field.
158+
159+
```graphql filename="Example: Create an Access Token"
160+
mutation CreateAccessTokenMutation($input: CreateOrganizationAccessTokenInput!) {
161+
deleteOrganizationAccessToken(input: $input) {
162+
ok {
163+
deletedOrganizationAccessTokenId
164+
}
165+
error {
166+
message
167+
}
168+
}
169+
}
170+
```

‎packages/web/docs/src/content/graphql-api/contract-management.mdx

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: Contract Management via the GraphQL API
3+
description: Learn how to manage contracts via the Hive Console GraphQL API.
4+
---
5+
6+
# Contract Management via the GraphQL API
7+
8+
The contracts of a target can be managed via the Hive Console GraphQL API. For more information,
9+
please refer to our [schema contracts documentation](/docs/schema-registry/contracts).
10+
11+
## Retrieve a list of all Contracts in Target
12+
13+
Use the `Target.contracts` field for retrieving a list of all contracts within the target.
14+
15+
```graphql
16+
query ContractTargets($targetId: ID!) {
17+
target(reference: { byId: $targetId }) {
18+
id
19+
contracts {
20+
edges {
21+
node {
22+
id
23+
contractName
24+
includeTags
25+
excludeTags
26+
removeUnreachableTypesFromPublicApiSchema
27+
isDisabled
28+
}
29+
}
30+
pageInfo {
31+
hasNextPage
32+
endCursor
33+
}
34+
}
35+
}
36+
}
37+
```
38+
39+
## Retrieve a list of all Active Contracts in Target
40+
41+
Use the `Target.activeContracts` field for retrieving a list of all contracts within the target.
42+
43+
```graphql
44+
query ActiveContractTargets($targetId: ID!) {
45+
target(reference: { byId: $targetId }) {
46+
id
47+
activeContracts {
48+
edges {
49+
node {
50+
id
51+
contractName
52+
includeTags
53+
excludeTags
54+
removeUnreachableTypesFromPublicApiSchema
55+
isDisabled
56+
}
57+
}
58+
pageInfo {
59+
hasNextPage
60+
endCursor
61+
}
62+
}
63+
}
64+
}
65+
```
66+
67+
### Create a Contract
68+
69+
Use the `Mutation.createContract` field for creating a new contract.
70+
71+
```graphql
72+
mutation CreateContract($input: CreateContractInput!) {
73+
createContract(input: $input) {
74+
ok {
75+
createdContract {
76+
id
77+
contractName
78+
includeTags
79+
excludeTags
80+
removeUnreachableTypesFromPublicApiSchema
81+
isDisabled
82+
}
83+
}
84+
error {
85+
message
86+
details {
87+
target
88+
contractName
89+
includeTags
90+
excludeTags
91+
}
92+
}
93+
}
94+
}
95+
```
96+
97+
## Disable a Contract
98+
99+
Use the `Mutation.disableContract` field for disabling a contract. **Note:** A disabled contract
100+
cannot be made active again.
101+
102+
```graphql
103+
mutation DisableContract($input: DisableContractInput!) {
104+
disableContract(input: $input) {
105+
ok {
106+
disabledContract {
107+
id
108+
contractName
109+
includeTags
110+
excludeTags
111+
removeUnreachableTypesFromPublicApiSchema
112+
isDisabled
113+
}
114+
}
115+
error {
116+
message
117+
}
118+
}
119+
}
120+
```
121+
122+
## Delete a Contract
123+
124+
This is not possible. Instead, disable the contract.

0 commit comments

Comments
 (0)