Cos'è siren?

SIREN: Un Hypermedia Type per API REST

SIREN è una specifica di hypermedia type progettata per rappresentare le entità e le azioni disponibili in un'API REST. L'obiettivo principale di SIREN è di fornire un formato strutturato e standardizzato per comunicare non solo i dati, ma anche le relazioni e le possibili transizioni di stato, consentendo ai client di scoprire dinamicamente le funzionalità dell'API.

Struttura Generale:

Un documento SIREN è rappresentato in JSON e contiene i seguenti elementi principali:

• class: (Opzionale) Un array di stringhe che descrivono semanticamente l'entità. Questo permette ai client di capire il tipo di entità che stanno ricevendo. Ad esempio, ["order", "shipping"]. [https://it.wikiwhat.page/kavramlar/Classe%20(SIREN)]

• properties: (Opzionale) Un oggetto JSON contenente i dati relativi all'entità. Questi sono i campi dati principali associati all'entità. Ad esempio, {"orderId": "12345", "total": 100}. [https://it.wikiwhat.page/kavramlar/Proprietà%20(SIREN)]

• entities: (Opzionale) Un array di sub-entità incorporate. Ogni sub-entità rappresenta una relazione con l'entità principale. Possono essere incorporate sia entità embedded link, sia embedded representation. [https://it.wikiwhat.page/kavramlar/Entità%20(SIREN)]

  • Embedded Link: Contengono solo un rel e un href che puntano a un'altra risorsa.
  • Embedded Representation: Contengono una rappresentazione completa di un'altra risorsa inline, con class, properties, entities e links.

• actions: (Opzionale) Un array di azioni possibili sull'entità. Ogni azione definisce un'operazione che può essere eseguita sull'entità, come POST, PUT, o DELETE. [https://it.wikiwhat.page/kavramlar/Azioni%20(SIREN)]

  • Ogni azione deve avere:
    • name: Un identificativo univoco per l'azione.
    • href: L'URL a cui inviare la richiesta per eseguire l'azione.
    • method: (Opzionale, default GET) Il metodo HTTP da utilizzare (es. GET, POST, PUT, DELETE).
    • fields: (Opzionale) Un array di campi che rappresentano i dati di input richiesti per eseguire l'azione. Ogni campo ha un name, type e value (opzionale).

• links: (Opzionale) Un array di link che rappresentano relazioni con altre risorse. Ogni link ha un rel (relation) e un href (Hypertext Reference). Il rel descrive la relazione tra la risorsa corrente e la risorsa puntata dall'href. [https://it.wikiwhat.page/kavramlar/Link%20(SIREN)]

Esempio:

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

Benefici di SIREN:

• Discoverability: Permette ai client di scoprire dinamicamente le funzionalità dell'API senza bisogno di documentazione statica.
• Loose Coupling: Riduce l'accoppiamento tra client e server, in quanto il client non ha bisogno di essere hardcoded con informazioni sull'API.
• Evolvibilità: L'API può evolvere senza rompere i client esistenti, a patto che le relazioni e le azioni fondamentali rimangano coerenti.
• Standardizzazione: Fornisce un formato standardizzato per la rappresentazione di hypermedia, facilitando l'interoperabilità tra diverse API.

In sintesi, SIREN è un hypermedia type robusto e flessibile per la costruzione di API RESTful, che promuove la discoverability, il loose coupling e l'evolvibilità.