Skip to content

Commit 462d895

Browse files
yolanferyyolanfery
authored
fix: add GraphQL documentation for static webapps + remove delete operations from webapp scope (HEXA-1653) (#1825)
1 parent f86f732 commit 462d895

2 files changed

Lines changed: 312 additions & 6 deletions

File tree

‎backend/hexa/webapps/graphql_proxy.py‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,6 @@
2929
Webapp.OperationScope.FILES_WRITE: {
3030
"prepareObjectUpload",
3131
"createBucketFolder",
32-
"deleteBucketObject",
3332
"writeFileContent",
3433
},
3534
Webapp.OperationScope.DATASETS_READ: {
@@ -41,12 +40,9 @@
4140
Webapp.OperationScope.DATASETS_WRITE: {
4241
"createDataset",
4342
"updateDataset",
44-
"deleteDataset",
4543
"createDatasetVersion",
4644
"updateDatasetVersion",
47-
"deleteDatasetVersion",
4845
"createDatasetVersionFile",
49-
"deleteDatasetLink",
5046
},
5147
Webapp.OperationScope.USER_READ: {"me", "workspace"},
5248
}

‎docs/en/static-webapps.md‎

Lines changed: 312 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,12 +63,18 @@ By default a static webapp has an empty `allowed_operations` list, which means i
6363
| `PIPELINES_READ` | `pipeline`, `pipelines`, `pipelineByCode`, `pipelineRun`, `pipelineVersion` |
6464
| `PIPELINES_RUN` | `runPipeline`, `stopPipeline` |
6565
| `FILES_READ` | `getFileByPath`, `readFileContent`, `prepareObjectDownload` |
66-
| `FILES_WRITE` | `prepareObjectUpload`, `createBucketFolder`, `deleteBucketObject`, `writeFileContent` |
66+
| `FILES_WRITE` | `prepareObjectUpload`, `createBucketFolder`, `writeFileContent` |
6767
| `DATASETS_READ` | `dataset`, `datasets`, `datasetVersion`, `datasetLink` |
68-
| `DATASETS_WRITE` | `createDataset`, `updateDataset`, `deleteDataset`, `createDatasetVersion`, `updateDatasetVersion`, `deleteDatasetVersion`, `createDatasetVersionFile`, `deleteDatasetLink` |
68+
| `DATASETS_WRITE` | `createDataset`, `updateDataset`, `createDatasetVersion`, `updateDatasetVersion`, `createDatasetVersionFile` |
6969

7070
Introspection fields `__typename`, `__schema`, `__type` are always allowed.
7171

72+
## Exploring the schema
73+
74+
The fastest way to design queries for a webapp is the interactive GraphQL playground at <https://app.openhexa.org/graphql/> (or `/graphql/` on your own install).
75+
76+
Note that the playground shows the **full** schema, not just what the webapp proxy allows. A query that works there can still return `403` from a webapp at runtime if its top-level field isn't covered by the webapp's [scopes](#scope-reference) — cross-check before pasting into webapp code.
77+
7278
## The `window.OPENHEXA` global
7379

7480
When OpenHEXA serves your static webapp's HTML it injects a small script before `</head>` that exposes:
@@ -93,6 +99,47 @@ Each example below is a complete `index.html` you can drop into a static webapp.
9399

94100
Displays the current user and workspace on load.
95101

102+
<details markdown="1">
103+
<summary>Schema</summary>
104+
105+
```graphql
106+
type Query {
107+
me: Me!
108+
workspace(slug: String!): Workspace
109+
}
110+
111+
type Me {
112+
user: User
113+
features: [FeatureFlag!]!
114+
permissions: MePermissions!
115+
}
116+
117+
type User {
118+
id: UUID!
119+
email: String!
120+
firstName: String
121+
lastName: String
122+
displayName: String!
123+
language: String!
124+
avatar: Avatar!
125+
}
126+
127+
type Workspace {
128+
slug: String!
129+
name: String!
130+
description: String
131+
countries: [Country!]!
132+
organization: Organization
133+
createdAt: DateTime!
134+
updatedAt: DateTime
135+
createdBy: User!
136+
}
137+
```
138+
139+
[Browse the full schema in the playground →](https://app.openhexa.org/graphql/)
140+
141+
</details>
142+
96143
```html
97144
<!DOCTYPE html>
98145
<html>
@@ -140,6 +187,46 @@ Displays the current user and workspace on load.
140187

141188
Lists every pipeline in the workspace.
142189

190+
<details markdown="1">
191+
<summary>Schema</summary>
192+
193+
```graphql
194+
type Query {
195+
pipelines(
196+
workspaceSlug: String
197+
name: String
198+
search: String
199+
tags: [String!]
200+
functionalType: PipelineFunctionalType
201+
lastRunStates: [PipelineRunStatus!]
202+
page: Int
203+
perPage: Int
204+
orderBy: PipelineOrderBy
205+
): PipelinesPage!
206+
}
207+
208+
type PipelinesPage {
209+
items: [Pipeline!]!
210+
pageNumber: Int!
211+
totalPages: Int!
212+
totalItems: Int!
213+
}
214+
215+
type Pipeline {
216+
id: UUID!
217+
code: String!
218+
name: String
219+
description: String
220+
schedule: String
221+
currentVersion: PipelineVersion
222+
type: PipelineType!
223+
}
224+
```
225+
226+
[Browse the full schema in the playground →](https://app.openhexa.org/graphql/)
227+
228+
</details>
229+
143230
```html
144231
<!DOCTYPE html>
145232
<html>
@@ -196,6 +283,60 @@ Lists every pipeline in the workspace.
196283

197284
Loads the list of pipelines on page open, lets you pick one from a dropdown, and runs it with a JSON config. Polls the run status until it terminates. Requires both `PIPELINES_READ` (to list) and `PIPELINES_RUN` (to launch).
198285

286+
<details markdown="1">
287+
<summary>Schema</summary>
288+
289+
```graphql
290+
type Query {
291+
pipelines(workspaceSlug: String, page: Int, perPage: Int): PipelinesPage!
292+
pipeline(id: UUID!): Pipeline
293+
pipelineRun(id: UUID!): PipelineRun
294+
}
295+
296+
type Mutation {
297+
runPipeline(input: RunPipelineInput): RunPipelineResult!
298+
stopPipeline(input: StopPipelineInput!): StopPipelineResult!
299+
}
300+
301+
input RunPipelineInput {
302+
id: UUID!
303+
versionId: UUID
304+
config: JSON!
305+
sendMailNotifications: Boolean
306+
enableDebugLogs: Boolean
307+
}
308+
309+
input StopPipelineInput {
310+
runId: UUID!
311+
}
312+
313+
type RunPipelineResult {
314+
success: Boolean!
315+
errors: [PipelineError!]!
316+
run: PipelineRun
317+
}
318+
319+
type StopPipelineResult {
320+
success: Boolean!
321+
errors: [PipelineError!]!
322+
}
323+
324+
type PipelineRun {
325+
id: UUID!
326+
status: PipelineRunStatus!
327+
progress: Int!
328+
executionDate: DateTime
329+
duration: Int
330+
outputs: [PipelineRunOutput!]!
331+
}
332+
333+
union PipelineRunOutput = BucketObject | GenericOutput | DatabaseTable
334+
```
335+
336+
[Browse the full schema in the playground →](https://app.openhexa.org/graphql/)
337+
338+
</details>
339+
199340
```html
200341
<!DOCTYPE html>
201342
<html>
@@ -301,6 +442,57 @@ Loads the list of pipelines on page open, lets you pick one from a dropdown, and
301442

302443
Lists CSV files in the workspace bucket on page load, lets you pick one from a dropdown, and renders the first 100 lines as a table. Requires both `USER_READ` (to list files via `workspace.bucket.objects`) and `FILES_READ` (to read content).
303444

445+
<details markdown="1">
446+
<summary>Schema</summary>
447+
448+
```graphql
449+
type Query {
450+
getFileByPath(workspaceSlug: String!, path: String!): BucketObject
451+
readFileContent(
452+
workspaceSlug: String!
453+
filePath: String!
454+
startLine: Int
455+
endLine: Int
456+
): ReadFileContentResult!
457+
}
458+
459+
type Mutation {
460+
prepareObjectDownload(input: PrepareObjectDownloadInput!): PrepareObjectDownloadResult!
461+
}
462+
463+
input PrepareObjectDownloadInput {
464+
workspaceSlug: String!
465+
objectKey: String!
466+
forceAttachment: Boolean = true
467+
}
468+
469+
type BucketObject {
470+
key: String!
471+
name: String!
472+
path: String!
473+
size: BigInt
474+
updatedAt: DateTime
475+
type: BucketObjectType!
476+
}
477+
478+
type ReadFileContentResult {
479+
success: Boolean!
480+
errors: [ReadFileContentError!]!
481+
content: String
482+
size: Int
483+
}
484+
485+
type PrepareObjectDownloadResult {
486+
success: Boolean!
487+
downloadUrl: URL
488+
errors: [PrepareObjectDownloadError!]!
489+
}
490+
```
491+
492+
[Browse the full schema in the playground →](https://app.openhexa.org/graphql/)
493+
494+
</details>
495+
304496
```html
305497
<!DOCTYPE html>
306498
<html>
@@ -413,6 +605,46 @@ Lists CSV files in the workspace bucket on page load, lets you pick one from a d
413605

414606
Pick a file, upload it via a presigned URL.
415607

608+
<details markdown="1">
609+
<summary>Schema</summary>
610+
611+
```graphql
612+
type Mutation {
613+
prepareObjectUpload(input: PrepareObjectUploadInput!): PrepareObjectUploadResult!
614+
writeFileContent(input: WriteFileContentInput!): WriteFileContentResult!
615+
createBucketFolder(input: CreateBucketFolderInput!): CreateBucketFolderResult!
616+
}
617+
618+
input PrepareObjectUploadInput {
619+
workspaceSlug: String!
620+
objectKey: String!
621+
contentType: String
622+
}
623+
624+
input WriteFileContentInput {
625+
workspaceSlug: String!
626+
filePath: String!
627+
content: String!
628+
overwrite: Boolean = false
629+
}
630+
631+
input CreateBucketFolderInput { workspaceSlug: String!, folderKey: String! }
632+
633+
type PrepareObjectUploadResult {
634+
uploadUrl: URL
635+
headers: JSON
636+
success: Boolean!
637+
errors: [PrepareObjectUploadError!]!
638+
}
639+
640+
type WriteFileContentResult { success: Boolean!, errors: [WriteFileContentError!]!, filePath: String, size: Int }
641+
type CreateBucketFolderResult { success: Boolean!, errors: [CreateBucketFolderError!]!, folder: BucketObject }
642+
```
643+
644+
[Browse the full schema in the playground →](https://app.openhexa.org/graphql/)
645+
646+
</details>
647+
416648
```html
417649
<!DOCTYPE html>
418650
<html>
@@ -479,6 +711,43 @@ Pick a file, upload it via a presigned URL.
479711

480712
Lists datasets visible to the workspace and their latest version.
481713

714+
<details markdown="1">
715+
<summary>Schema</summary>
716+
717+
```graphql
718+
type Query {
719+
datasets(query: String, page: Int = 1, perPage: Int = 15): DatasetPage!
720+
dataset(id: ID!): Dataset
721+
datasetVersion(id: ID!): DatasetVersion
722+
datasetLink(id: ID!): DatasetLink
723+
}
724+
725+
type DatasetPage {
726+
totalPages: Int!
727+
totalItems: Int!
728+
pageNumber: Int!
729+
items: [Dataset!]!
730+
}
731+
732+
type Dataset {
733+
id: ID!
734+
slug: String!
735+
name: String!
736+
description: String
737+
createdAt: DateTime!
738+
updatedAt: DateTime!
739+
createdBy: User
740+
workspace: Workspace
741+
versions(page: Int = 1, perPage: Int = 15): DatasetVersionPage!
742+
latestVersion: DatasetVersion
743+
links(page: Int = 1, perPage: Int = 15): DatasetLinkPage!
744+
}
745+
```
746+
747+
[Browse the full schema in the playground →](https://app.openhexa.org/graphql/)
748+
749+
</details>
750+
482751
```html
483752
<!DOCTYPE html>
484753
<html>
@@ -544,6 +813,47 @@ Lists datasets visible to the workspace and their latest version.
544813

545814
Tiny form that creates a dataset and prints the new id/slug.
546815

816+
<details markdown="1">
817+
<summary>Schema</summary>
818+
819+
```graphql
820+
type Mutation {
821+
createDataset(input: CreateDatasetInput!): CreateDatasetResult!
822+
createDatasetVersion(input: CreateDatasetVersionInput!): CreateDatasetVersionResult!
823+
createDatasetVersionFile(input: CreateDatasetVersionFileInput!): CreateDatasetVersionFileResult!
824+
updateDataset(input: UpdateDatasetInput!): UpdateDatasetResult!
825+
updateDatasetVersion(input: UpdateDatasetVersionInput!): UpdateDatasetVersionResult!
826+
}
827+
828+
input CreateDatasetInput {
829+
workspaceSlug: String!
830+
name: String!
831+
description: String
832+
files: [DatasetVersionFileContentInput!]
833+
}
834+
835+
input DatasetVersionFileContentInput { uri: String!, contentType: String!, content: String! }
836+
837+
input CreateDatasetVersionInput {
838+
datasetId: ID!
839+
name: String!
840+
changelog: String
841+
files: [DatasetVersionFileContentInput!]
842+
}
843+
844+
input CreateDatasetVersionFileInput { versionId: ID!, contentType: String!, uri: String! }
845+
846+
type CreateDatasetResult { link: DatasetLink, dataset: Dataset, success: Boolean!, errors: [CreateDatasetError!]! }
847+
type CreateDatasetVersionResult { version: DatasetVersion, success: Boolean!, errors: [CreateDatasetVersionError!]! }
848+
type CreateDatasetVersionFileResult { file: DatasetVersionFile, uploadUrl: String!, success: Boolean!, errors: [CreateDatasetVersionFileError!]! }
849+
type UpdateDatasetResult { dataset: Dataset, success: Boolean!, errors: [UpdateDatasetError!]! }
850+
type UpdateDatasetVersionResult { version: DatasetVersion, success: Boolean!, errors: [UpdateDatasetVersionError!]! }
851+
```
852+
853+
[Browse the full schema in the playground →](https://app.openhexa.org/graphql/)
854+
855+
</details>
856+
547857
```html
548858
<!DOCTYPE html>
549859
<html>

0 commit comments

Comments
 (0)