Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

Enhance Response cache-control header

Ouverte
  • Quelque chose ne va pas ?
#2,784 5 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

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é
À clarifier
Activité
À l'abandon
Domaine
api, documentation

Piste de recherche

Commencez par examiner OpenAPI Header Object, la prise en charge de JSON Schema et les exemples de Cache-Control dans cette issue. Aucun fichier du dépôt ni aucun test n’est identifié ; la finalisation nécessiterait de convenir d’une manière précise et interopérable de représenter les directives séparées par des virgules et les directives clé-valeur telles que max-age, puis de la documenter.

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

Description

headers http param serialization

I have been trying to use Open API to specify the expected Cache rules for some API routes

While defining such rules through the Expires and/or Pragma headers can be quite simple (a date for Expires & the no-cache constant for Pragma), they are not the modern way to do it. Pragma is deprecated, and Expires is ignored when Cache-Control is defined.

Cache-Control is also nowadays supported by all clients making it the most obvious solution to define the caching rules.

Unfortunately, the current OPEN API Header Object support looks a bit limited for Cache-Control. Using pure JSON Schema definition might produce unexpected behavior without dedicated context for this header or for headers having similar Design.

This header value is defined as a comma-seperated list of properties called directives
If all directives were simple strings I could write something like that if I allowed any of them (or restrict to the on I accept by design)

      responses:
        200:
          description: "The request was successfully treated."
          headers:
            Cache-Control: 
              schema:
                type: array
                items:
                  type: string
                  enum:
                  - public
                  - private
                  - no-cache
                  - no-store
                  - must-revalidate
                  - proxy-revalidate
                  - immutable
                  - no-transform
                  - only-if-cached

If I want my route to prevent response to be cached I can easily design it a more simple way

            Cache-Control: 
              schema:
                type: string
                enum:
                - no-store

Or with the last JSON-Schema edition support of constants

            Cache-Control: 
              schema:
                const: "no-store"

But some of the most important cache control properties are key value pairs like max-age=300

I tried to express it the most reiable still simple way using adavanced JSON Schema feature unfortunately not really well supported (yet?) by Open API implementations

Sample 1

  • Pro:
    • shortest
  • Cons:
    • forbid different property order
    • forbid potentially acceptable other cache-control properties
    • not really the most inspectable
            Cache-Control: 
              schema:
                const: "public, max-age=300"

Sample 2

  • Pro:
    • still short
  • Cons:
    • ⚠️❌ the specification doesn't say how to serialize the object
            Cache-Control: 
              schema:
                const: ["public", {"max-age": 300}]

Sample 3

  • Pro:
    • explicit, no need for const support
  • Cons:
    • very verbose
    • pretty sure enum not well supported for numbers
    • ⚠️❌ the specification still doesn't say how to serialize the object
            Cache-Control: 
              schema:
                type: array
                items:
                  allOf:
                  - type: string
                    enum:
                    - public
                  - type: object
                    properties:
                      max-age:
                        type: number
                        enum:
                        - 300
                      required:
                      - max-age
Langage dominant
Markdown
Étoiles
31.2k
Forks
9.2k
Merge moyen
2 j 9 h
PR mergées (30 j)
17

Préparer son environnement

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.