Web BizarroWeb Bizarro

Suscríbete a nuestro Newsletter

X

Únete a nuestra lista de correos para recibir semanalmente actualizaciones de nuestro contenido.

RAML para documentar Rest API

RAML para documentar Rest API 02.FEB.15

Alvaro José Rios Ch
Fundador WebBizarro

Los Rest API son muy utilizados en la actualidad por los desarrolladores, ya que son muy flexibles y te permiten crear aplicaciones para múltiples plataformas centralizadas sobre un mismo sistema, lo que ahorra mucho tiempo en desarrollo y posteriormente en mantenimiento. Sin embargo de nada vale tener un Rest API bien desarrollada si no está bien documentada.

RAML, el lenguaje de modelado para las Rest API por sus siglas en ingles es un sistema que te permite documentar las API fácilmente y bajo un estándar fácil de entender y seguir. RAML esta basado YAML por lo que si estas familiarizado con este formato debe ser fácil de entender para ti, de lo contrario no te preocupes tampoco es algo complicado.

RAML te permite definir y documentar todas las secciones de tu REST API, desde los parámetros que recibe hasta los posibles mensajes de error que pueden aparecer. En el ejemplo siguiente podemos ver como puede definirse el api.

/media/popular:
  displayName: Most Popular Media
  get:
    description: |
      Get a list of what media is most popular at the moment.
    responses:
      503:
        description: |
          The service is currently unavailable or you exceeded the maximum requests
          per hour allowed to your application.
        headers:
          X-waiting-period:
            description: |
              The number of seconds to wait before you can attempt to make a request again.
            type: integer
            required: yes
            minimum: 1
            maximum: 3600
            example: 34

Como pueden ver es muy especifico lo que es una bendición para los desarrolladores que van a crear el API como para los que van a hacer mantenimiento, ya que hay una idea clara de como debe comportarse cada uno de los métodos, así que la próxima vez que pienses en hacer un Rest API, deberías pensar primero en RAML para definirla y documentarla.