Descansando

• basado en arquitectura cliente-servidor
• y quiere servir a diferentes clientes a través del protocolo HTTP
• y desea utilizar las restricciones REST descritas anteriormente

############################################################################
#                              Movie Apis Definitions                                #
############################################################################
# Code completion support is available so start typing for available options.
swagger: '2.0'

# This is your document metadata
info:
  version: "1.0.1"
  title: The movie api

# Describe your paths here
paths:
  # This is a path endpoint. Change it.
  /movies:
    # This is a HTTP operation
    get:
      # Describe this verb here. Note: you can use markdown
      description: Returns all movies
      operationId: getMovies
      # Expected responses for this operation:
      responses:
        # Response code
        200:
          description: Successful response
          # A schema describing your response object.
          # Use JSON Schema format
          schema:
            title: ArrayOfMovies
            type: array
            items:
               $ref: '#/definitions/movie'
        default:
          description: Error
          schema:
            $ref: 'https://zalando.github.io/problem/schema.yaml#/Problem'
    post:
      description: Add a new movie
      operationId: addMovie
      parameters:
        - name: movie
          in: body
          description: The new movie
          required: true
          schema:
            $ref: '#/definitions/movie'
      responses:
        '201':
          description: The new movie
          schema:
            $ref: '#/definitions/movie'
        default:
          description: Error
          schema:
            $ref: 'https://zalando.github.io/problem/schema.yaml#/Problem'
  /movies/{id}:
    parameters:
      - name: id
        in: path
        description: ID of the movie
        required: true
        type: integer
        format: int64
    get:
      description: Returns a single movie
      operationId: getMovieById
      responses:
        200:
          description: Successful response
          schema:
             $ref: '#/definitions/movie'
        default:
          description: Error
          schema:
            $ref: 'https://zalando.github.io/problem/schema.yaml#/Problem'
    put:
      description: Update an existing movie
      operationId: updateMovieById
      parameters:
        - name: movie
          in: body
          description: The movie
          required: true
          schema:
            $ref: '#/definitions/movie'
      responses:
        '200':
          description: The new movie
          schema:
            $ref: '#/definitions/movie'
        default:
          description: Error
          schema:
            $ref: 'https://zalando.github.io/problem/schema.yaml#/Problem'
    delete:
      description: Delete a movie
      operationId: deleteMovieById
      responses:
        '204':
          description: Movie deleted
        default:
          description: Error
          schema:
            $ref: 'https://zalando.github.io/problem/schema.yaml#/Problem'
definitions:
  movie:
    type: object
    required:
      - id
      - title
    properties:
      id:
        type: integer
        format: int64
      title:
        type: string
      ratings:
        type: object
        properties:
          criticsScore:
            type: integer
            minimum: 0
            maximum: 100
          audienceScore:
            type: integer
            minimum: 0
            maximum: 100
      criticsConsensus:
        type: string
      abridgedDirectors:
        type: array
        items:
          type: string
      abridgedCast:
        type: array
        items:
           $ref: '#/definitions/cast'
      posters:
        $ref: '#/definitions/posters'
  cast:
    type: object
    required:
      - id
      - name
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      characters:
        type: array
        items:
          type: string
  posters:
    properties:
      thumbnail:
        type: string
        format: uri
      profile:
        type: string
        format: uri
      detailed:
        type: string
        format: uri
      original:
        type: string
        format: uri

• Utilice OAuth2 para proteger su API.
• Utilice un token de portador de caducidad automática para la autenticación ( Authorisation: Bearer f0ca4227-64c4-44e1-89e6-b27c62ac2eb6).
• Requerir HTTPS.
• Considere usar tokens web JSON .
• Refuerce el uso de los encabezados Content-Type y Accept-Type incluso si usa JSON como predeterminado tanto para las solicitudes como para las respuestas.

e.g.  Content-Type: application/json Accept-Type: application/json

• Las respuestas contienen encabezado:X-Frame-Options: deny

• Nivel 0: define un URI y todas las operaciones son solicitudes POST a este URI.
• Nivel 1: cree URI separados para recursos individuales.
• Nivel 2: use métodos HTTP para definir operaciones en los recursos.
• Nivel 3: Usar hipermedia (HATEOAS, descrito a continuación).

{    
      "healthy": true,   
      "dependencies":
       {         "name": "moviesapi", 
        "healthy": true      
       } 
 }

• Para un método POST, el URI representa un recurso principal de la nueva entidad, como una colección. Por ejemplo, para crear una nueva película, el URI podría ser /api/movies. El servidor crea la entidad y le asigna un nuevo URI, como /api/movies/6812360. Este URI se devuelve en el encabezado Ubicación de la respuesta. Cada vez que el cliente envía una solicitud, el servidor creará una nueva entidad con una nueva URI.
• Para un método PUT, el URI identifica la entidad. Si ya existe una entidad con ese URI, el servidor actualiza la entidad existente con la versión en la solicitud.

• Cache-Control : el número máximo de segundos (ttl) que se puede almacenar en caché una respuesta. ( Cache-Control: public, 360o Cache-Control: no-store)
• El almacenamiento en caché sólido minimiza la cantidad de solicitudes que recibe un servidor
• Considere el almacenamiento en caché débil a través del ETagencabezado de respuesta
• ETag : use un hash SHA1 para la versión de un recurso. Asegúrese de incluir el tipo de medio en el valor hash, porque eso hace una representación diferente. ( ETag: "2dbc2fd2358e1ea1b7a6bc08ea647b9a337ac92d"). El cliente necesita enviar un encabezado If-None-Match para que este mecanismo funcione.
• El almacenamiento en caché débil minimiza el trabajo que debe hacer un servidor (pero no la cantidad de solicitudes que recibe)
• Habilite el almacenamiento en caché basado en encabezados en todos los proxies y clientes (p. ej., NGINX, Apache, APIM) para aumentar la velocidad y la solidez
• No hay datos que comprometan la privacidad o la seguridad en las URL

• Implemente el cifrado de contenido en los puntos finales más lejanos (en el servidor REST, no en los proxies o APIM)
• Cuando se utiliza la firma de contenido, esto se hace después de que el contenido esté (opcionalmente) cifrado.
• Use el encabezado X-Signing-Algorithm para comunicar el tipo de firma de contenido ( X-Signing-Algorithm: RS256)
• Use el encabezado X-SHA256-Checksum para comunicar el valor hash SHA256 del contenido ( X-SHA256-Checksum: e1d58ba0a1810d6dca5f086e6e36a9d81a8d4bb00378bdab30bdb205e7473f87)
• Use el encabezado X-Encryption-Algorithm para comunicar el tipo de cifrado de contenido ( X-Encryption-Algorithm: A128CBC-HS256)

• Consistente (evitar sorpresas siendo predecible)
• Cohesivo (solo enumera puntos finales con dependencia funcional)
• Completo (tiene todos los puntos finales necesarios para su propósito)
• Mínimo (no más puntos finales de los necesarios para estar completo, sin características)
• Encapsular (ocultar detalles de implementación)
• autoexplicativo
• Documentado (si la autoexplicación no es suficiente)

• WSO2
• Apigeo
• IBM
• Software AG
• Mulesoft