O que é siren?

Siren

Siren é uma especificação para representar hyperlinks em uma API, facilitando a navegação e descoberta de recursos. É um formato de hipermídia que visa ser simples e flexível para representar o estado de um recurso e as ações que podem ser realizadas nesse recurso.

Características Principais:

• Entidades: Representam um estado de um recurso. Contêm propriedades (dados), links (para recursos relacionados), actions (ações que podem ser realizadas no recurso) e entities incorporadas (recursos aninhados).
• Propriedades: São pares chave-valor que representam os dados associados à entidade.
• Links: Fornecem relações semânticas entre a entidade atual e outros recursos. Cada link tem um rel (relação) que descreve o tipo de relação e um href (URL) que indica o destino do link.
• Actions: Representam as operações que podem ser executadas na entidade. Cada ação tem um nome, uma href (URL para executar a ação), um method (verbo HTTP) e um fields (conjunto de campos que precisam ser enviados com a requisição).
• Entities Incorporadas: Permitem representar recursos aninhados dentro da entidade principal. Podem ser sub-entities (recursos relacionados que fazem parte da entidade principal) ou linked-entities (recursos relacionados que são referenciados por um link).
• Class: Um array de strings que representam a semântica da entidade. É usado para categorizar ou classificar a entidade para facilitar a descoberta e o processamento.
• Title: Um título curto e legível para a entidade.

Vantagens de usar Siren:

• Descobrimento de Recursos: Facilita a descoberta de recursos e ações disponíveis em uma API.
• Flexibilidade: Pode ser usado com diferentes tipos de APIs, incluindo REST e GraphQL.
• Simplicidade: É relativamente simples de entender e implementar.
• Desacoplamento: Permite que o cliente interaja com a API sem precisar conhecer os detalhes da sua implementação.

Exemplo:

{
  "class": ["order"],
  "properties": {
    "orderNumber": 123,
    "status": "pending"
  },
  "entities": [
    {
      "class": ["items", "collection"],
      "rel": ["http://example.com/rels/order-items"],
      "href": "http://api.example.com/orders/123/items"
    }
  ],
  "actions": [
    {
      "name": "add-item",
      "title": "Add Item",
      "method": "POST",
      "href": "http://api.example.com/orders/123/items",
      "fields": [
        { "name": "name", "type": "text" },
        { "name": "quantity", "type": "number" }
      ]
    }
  ],
  "links": [
    { "rel": ["self"], "href": "http://api.example.com/orders/123" }
  ]
}

Este exemplo representa um pedido (order). Contém propriedades como orderNumber e status. Possui uma entity incorporada que representa os itens do pedido. Tem uma action para adicionar itens ao pedido e um link para o próprio pedido.