|
1 | | -The *create resource* operation requests the creation of a new resource on the server. The resource can be a non-container (data) resource or a container (collection) resource. The operation can either let the server assign a new identifier within a target container (like creating a new file in a folder), or use a client-specified identifier (creating or overwriting at a specific path). |
2 | | - |
3 | | -**Inputs:** |
4 | | - |
5 | | -* **Target location:** Either a *target container identifier* (when the client wants the server to assign a name within that container) **or** a *full target resource identifier* (when the client specifies the exact desired identifier for the new resource). |
6 | | - |
7 | | -* **Resource content:** The content to store in the resource (binary or text). This is optional to allow creation of an empty container or an empty resource. |
8 | | - |
9 | | -* **Suggested name:** An optional hint for naming (when the server will assign the identifier). For example, the client may propose a filename or resource name, which the server may use or adjust. |
10 | | - |
11 | | -* **Media type:** The MIME media type or format of the content (e.g., `text/plain`, `application/json`). This helps the server understand how to store and serve the content. It may be mandatory for some protocols when content is provided (and may be omitted if creating an empty container with no content). |
12 | | - |
13 | | -**Behavior:** |
14 | | - |
15 | | -* If a *target container* is provided, the server will create a new resource as a member of that container. The server determines the new resource’s identifier (often incorporating the suggested name, if provided and allowed). The new resource is then added to the specified container’s member list. |
16 | | - |
17 | | -* If a *full target identifier* (including the desired name/path) is provided, the server will attempt to create a resource at that exact identifier. If a full target identifier is provided and a resource already exists at that identifier, the server **MUST** fail with a Conflict response, unless the client explicitly indicates that overwriting is acceptable. |
18 | | - |
19 | | -* The server **MAY** enforce additional constraints on creation. For example, it may have size limits, quota checks, or restrictions on allowed media types or file extensions. If any such constraint is violated (e.g., the content is too large or an unsupported type), the server will reject the operation with an appropriate error. |
20 | | - |
21 | | -* Upon successful creation, the new resource is persistently stored and linked into the logical container hierarchy. The server will assign an identifier, if needed, and make the resource available for future operations. The identifier (e.g., a URI or path) of the newly created resource **MUST** be returned to the client (so the client knows how to refer to it). The creation is atomic — if any step fails, no new resource is created (or any partial resource is cleaned up). |
22 | | - |
23 | | -**Possible Responses:** *(on the abstract operation level, not tied to a specific protocol)* |
24 | | - |
25 | | -* **Created:** The operation succeeded in creating a new resource. The response includes the new resource’s identifier and possibly a minimal representation or metadata (e.g., an ETag or version number). |
26 | | - |
27 | | -* **Bad Request:** The request was malformed or violated constraints (e.g., missing required inputs, invalid identifier, disallowed media type, or size limits exceeded). The resource was not created. |
28 | | - |
29 | | -* **Not Permitted:** The client is not authorized to create a resource in the target location. |
30 | | - |
31 | | -* **Conflict:** A resource at the target identifier already exists and the server does not allow overwrite (or a naming conflict occurred). No new resource was created, and any existing resource remains unchanged. |
32 | | - |
33 | | -* **Not Found:** (If applicable) The specified target container does not exist or cannot be found. This could also be treated as a type of Bad Request or Not Permitted, depending on the cause (e.g., if the container is missing or the client lacks access permission). |
34 | | - |
| 1 | +The *create resource* operation requests the creation of a new resource on the server. The resource can be a non-container (data) resource or a container (collection) resource. The operation can either let the server assign a new identifier within a target container (like creating a new file in a folder), or use a client-specified identifier (creating or overwriting at a specific path). |
| 2 | + |
| 3 | +**Inputs:** |
| 4 | + |
| 5 | +* **Target location:** Either a *target container identifier* (when the client wants the server to assign a name within that container) **or** a *full target resource identifier* (when the client specifies the exact desired identifier for the new resource). |
| 6 | + |
| 7 | +* **Resource content:** The content to store in the resource (binary or text). This is optional to allow creation of an empty container or an empty resource. |
| 8 | + |
| 9 | +* **Suggested name:** An optional hint for naming (when the server will assign the identifier). For example, the client may propose a filename or resource name, which the server may use or adjust. |
| 10 | + |
| 11 | +* **Media type:** The MIME media type or format of the content (e.g., `text/plain`, `application/json`). This helps the server understand how to store and serve the content. It may be mandatory for some protocols when content is provided (and may be omitted if creating an empty container with no content). |
| 12 | + |
| 13 | +**Behavior:** |
| 14 | + |
| 15 | +* If a *target container* is provided, the server will create a new resource as a member of that container. The server determines the new resource’s identifier (often incorporating the suggested name, if provided and allowed). The new resource is then added to the specified container’s member list. |
| 16 | + |
| 17 | +* If a *full target identifier* (including the desired name/path) is provided, the server will attempt to create a resource at that exact identifier. If a full target identifier is provided and a resource already exists at that identifier, the server **MUST** fail with a Conflict response, unless the client explicitly indicates that overwriting is acceptable. |
| 18 | + |
| 19 | +* The server **MAY** enforce additional constraints on creation. For example, it may have size limits, quota checks, or restrictions on allowed media types or file extensions. If any such constraint is violated (e.g., the content is too large or an unsupported type), the server will reject the operation with an appropriate error. |
| 20 | + |
| 21 | +* Upon successful creation, the new resource is persistently stored and linked into the logical container hierarchy. The server will assign an identifier, if needed, and make the resource available for future operations. The identifier (e.g., a URI or path) of the newly created resource **MUST** be returned to the client (so the client knows how to refer to it). The creation is atomic — if any step fails, no new resource is created (or any partial resource is cleaned up). |
| 22 | + |
| 23 | +**Possible Responses:** *(on the abstract operation level, not tied to a specific protocol)* |
| 24 | + |
| 25 | +* **Created:** The operation succeeded in creating a new resource. The response includes the new resource’s identifier and possibly a minimal representation or metadata (e.g., an ETag or version number). |
| 26 | + |
| 27 | +* **Bad Request:** The request was malformed or violated constraints (e.g., missing required inputs, invalid identifier, disallowed media type, or size limits exceeded). The resource was not created. |
| 28 | + |
| 29 | +* **Not Permitted:** The client is not authorized to create a resource in the target location. |
| 30 | + |
| 31 | +* **Conflict:** A resource at the target identifier already exists and the server does not allow overwrite (or a naming conflict occurred). No new resource was created, and any existing resource remains unchanged. |
| 32 | + |
| 33 | +* **Not Found:** (If applicable) The specified target container does not exist or cannot be found. This could also be treated as a type of Bad Request or Not Permitted, depending on the cause (e.g., if the container is missing or the client lacks access permission). |
| 34 | + |
35 | 35 | * **Unknown Error:** An internal server error occurred, or some unexpected condition prevented the creation. This is a catch-all for failures not covered by more specific errors. The response would indicate that the server failed the operation (and ideally include an error message or code). |
0 commit comments