Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

API Versioning

Abierto
  • ¿Algo no está bien?
#5 1 comentario 3 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Estancado
Área
api, backend-api-design, documentation

Línea de trabajo

Comienza con la sección API Lifecycle Management y su referencia a RFC4627; después, revisa las estrategias establecidas de versionado de las API REST de NRPP y BC Wildfire mencionadas en la issue. Se considera terminado cuando las directrices explican correctamente una estrategia de versionado de API que cubra cambios más amplios en la API sin depender de una interpretación no compatible del tipo de medio.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

feedback

The section on API Lifecycle Management prescribes identifying a version number in the mime type of a requests ACCEPT header and references RFC4627 as an endorsement of this practice.

The RFC4627 does not at all endorse using the version component of a mime type to indicate an API version. It is specific to indicating the version of a JSON structure. It is possible for a single version of an API to support many different representations of the same resource.

A new version of an API can include changes other than the addition or deprecation of supported resource structures. Specific examples being new behavior in existing interfaces, new workflows, new endpoints, deprecated endpoints, new SLAs, etc... The API Guidelines should provide a versioning strategy that addresses API changes; the mime type versioning does not.

(We have an established API versioning strategy for the NRPP and BC Wildfire Rest APIs that uses a separate HTTP Header to indicate the desired version of the API.)

Also many of the frameworks that we use to build our REST services, including Jersey, Spring, and CFX do not support custom mine types out of the box and require considerable configuration to provide custom handlers to support the serialization of the custom types. The frameworks support application\json and application\xml out of the box with no additional effort.

As standard tools do not know what to do with the custom mime types it will also be more difficult for new clients to consume the APIs that use a mime type versioning strategy.

Lenguaje dominante
Sin datos de lenguaje
Estrellas
34
Forks
10
Sin PR fusionados en 30 d

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de bcgov/api-guidelines

Todos los issues de bcgov/api-guidelines

Issues similares

Más issues de Backend & API Design

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.