search

gentics / mesh-incubator

Project which is home for planned enhancements for Gentics Mesh
3 stars 0 forks source link

Add binary lists and binaries for micronodes #228

Open philippguertler opened 4 years ago

philippguertler commented 4 years ago

The API for getting or creating binaries is as follows:

OpenAPI 3.0.2 Specification ```yml openapi: '3.0.2' info: title: Gentics Mesh version: '2' paths: '/{project}/nodes/{nodeUuid}/binary/{fieldPath}': get: summary: Downloads a binary from a node. responses: 200: description: "A binary file" post: summary: Uploads a binary to a node. requestBody: content: multipart/form-data: schema: type: object properties: language: description: Language of the node content which contains the binary field which should be updated. type: string version: description: Version of the node which should be updated. This information is used to determine conflicting updates. type: string binary: description: Single binary file part. type: string format: binary listMode: description: >- How the binary should be inserted into a list. This is ignored if the path is not a list. The following modes are available: * `append` - Appends the binary to the end of the list. * `prepend` - Puts the binary to the beginning of the list, increasing the index of all other elements. * `insert` - Inserts the binary to the given index, increasing the index of all subsequent items. * `replace` - Replaces the binary at the given index. `insert` and `replace` can only be used when an index for the binary list field is provided in the `fieldPath` path parameter. The index in `fieldPath` is ignored if the mode is `append` or `prepend`. The default value is `append` if the {fieldPath} refers to a binary list, `insert` if it refers to an element inside a list. type: string enum: [append, prepend, insert, replace] responses: 200: description: "The node response of the updated node." 400: description: "Invalid listMode." parameters: - $ref: '#/components/parameters/projectParam' - $ref: '#/components/parameters/nodeUuidParam' - $ref: '#/components/parameters/fieldPathParam' components: parameters: projectParam: name: project in: path description: The project of the node. required: true schema: type: string nodeUuidParam: name: nodeUuid in: path description: The uuid of the node. required: true schema: type: string fieldPathParam: name: fieldPath in: path description: >- `{fieldPath}` describes the location of a field inside a node. All indices for list fields are zero-based. This table gives examples for all cases: | Field | Path | Example | |-------------------------------------|-----------------------------------------------------------------------------|-----------------------| | Field | `{fieldName}` | `image` | | List field | `{fieldName}/{index}` | `images/2` | | Field in micronode field | `{micronodeFieldName}/{fieldName}` | `header/image` | | Field in micronode list | `{micronodeFieldName}/{micronodeIndex}/{fieldName}` | `contents/1/image` | | Field list in micronode | `{micronodeFieldName}/{fieldName}/{fieldIndex}` | `content/images/3` | | Field list in micronode list | `{micronodeFieldName}/{micronodeIndex}/{fieldName}/{fieldIndex}` | `contents/2/images/1` | required: true schema: type: string ```

Use https://editor.swagger.io/ and insert the above specification to view the documentation. Webroot requests to list items or binaries in micronodes are not possible.

Additionally, the binary uuid should be exposed in the node response to allow for removing or reordering binaries in a list, similar to micronode lists.

philippguertler commented 4 years ago

Tasks:

Jotschi commented 4 years ago

Maybe it would be easier and more consistent to use a dedicated endpoint to CRUD binary data. This way we would not clutter and over-complicate the current node API.