Vary presence and requirement of properties with CRUD operation

Ouverte
#1,497 21 commentaires 10 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
25/100
Type d'issue
Fonctionnalité
Clarté
Plutôt claire
Activité
À l'abandon
Stack technique
openapi
Domaine
api

Piste de recherche

Commencez par examiner le tableau des extensions du fournisseur de l'issue avec la sémantique OpenAPI existante pour readOnly, writeOnly et required. La tâche sera considérée comme terminée lorsqu'une spécification approuvée de la présence et des exigences des propriétés dépendantes de CRUD sera définie, y compris les règles de validation et les interactions avec la composition et les schémas polymorphes.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

schema-object

Properties of a schema could be marked as readOnly or writeOnly if they should not be used respectively in a request or response. Additionally, required properties are present in the required field. Request vs response is the only criteria that can alter a resource schema.

This was not sufficient to describe our legacy REST APIs where presence and requirement of resource's properties is highly dependent of CRUD operation. The was due, in part, to wrong design choices. However, we faced generic situations that cannot be expressed for example:

  • Write once / immutable property: for properties like slug or identifier. Those properties should not be part of update request.
  • Server side default value: this kind of property is required only in response.

All this can be achieved using composition. I don't think that's a reasonable solution because:

  • contract is not more human readable as resources are split in many schema
  • for polymorphic resources (using oneOf), there is too many different schema to create and duplication is inevitable

We used following vendor extensions to be able to produce the documentation of our API:

Field Name Type Description
x-createOnly boolean Relevant only for Schema "properties" definitions. Declares the property as "create only". This means that it MAY be sent as part of a POST request but SHOULD NOT be sent as part of the response or any other request type. If the property is marked as x-createOnly being true and is in the required list, the required will take effect on the POST request only. A property MUST NOT be marked as both x-createOnly and readOnly, writeOnly, x-updateOnly, x-createForbidden or x-updateForbidden being true. Default value is false.
x-updateOnly boolean Relevant only for Schema "properties" definitions. Declares the property as "update only". This means that it MAY be sent as part of a PUT request but SHOULD NOT be sent as part of the response or any other request type. If the property is marked as x-updateOnly being true and is in the required list, the required will take effect on the PUT request only. A property MUST NOT be marked as both x-updateOnly and readOnly, writeOnly, x-createOnly, x-createForbidden or x-updateForbidden being true. Default value is false.
x-createForbidden boolean Relevant only for Schema "properties" definitions. Declares the property as "create forbidden". This means that it MAY be sent as part of a PUT request or be sent as part of the response but SHOULD NOT be sent as part of any other request type. If the property is marked as x-createForbidden being true and is in the required list, the required will take effect on the PUT request and the response only. A property MUST NOT be marked as both x-createForbidden and readOnly, writeOnly, x-createOnly, x-updateOnly or x-updateForbidden being true. Default value is false.
x-updateForbidden boolean Relevant only for Schema "properties" definitions. Declares the property as "create and read only". This means that it MAY be sent as part of a POST request or be sent as part of the response but SHOULD NOT be sent as part of any other request type. If the property is marked as x-updateForbidden being true and is in the required list, the required will take effect on the POST request and the response only. A property MUST NOT be marked as both x-updateForbidden and readOnly, writeOnly, x-createOnly, x-updateOnly or x-createForbidden being true. Default value is false.
x-requiredCreate [string] List properties required in the POST request.
x-requiredUpdate [string] List properties requires in the PUT request.
x-requiredRead [string] List properties required in the response.

Being able to describe requirement and presence of resource's properties based on usage context could be a great enhancement.

Langage dominant
Markdown
Étoiles
31.2k
Forks
9.2k
Merge moyen
6 h 37 min
PR mergées (30 j)
27

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de OAI/OpenAPI-Specification

Toutes les issues de OAI/OpenAPI-Specification

Issues similaires

Plus d'issues Backend & API Design

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.