La Pagination de la réponse de la charge utile à partir d'une API RESTful

ReSTful Api sont consommés principalement par les autres systèmes, c'est pourquoi j'ai mis la pagination des données dans les en-têtes de réponse. Cependant, certaines API, les consommateurs ne peuvent pas avoir un accès direct pour les en-têtes de réponse, ou peut-être la construction d'un UX au-dessus de votre API, ainsi qu'en fournissant un moyen de récupérer (sur demande) les métadonnées dans la réponse JSON est un plus.

Je crois que votre mise en œuvre devrait inclure lisibles à la machine de métadonnées par défaut, et lisible par l'homme, les métadonnées lors de la demande. L'lisible par l'homme, les métadonnées peuvent être retournés avec à chaque demande, si vous le souhaitez, ou, de préférence, à la demande via un paramètre de requête, comme include=metadata ou include_metadata=true.

Dans votre scénario, je dirais l'URI pour chaque produit avec l'enregistrement. Cela rend plus facile pour les API des consommateurs pour créer des liens vers les produits individuels. Je voudrais également mettre quelques attentes raisonnables que par les limites de ma pagination à la demande. La mise en œuvre et documenter les paramètres par défaut pour la taille de la page est une pratique acceptable. Par exemple, L'API GitHub définit la taille de page par défaut de 30 enregistrements avec un maximum de 100, plus fixe un taux limite sur le nombre de fois où vous pouvez interroger l'API. Si votre API a une taille de page par défaut, puis la chaîne de requête pouvez simplement spécifier l'index de la page.

Dans la lisible par l'homme, scénario, lors de la navigation à /products?page=5&per_page=20&include=metadata, la réponse pourrait être:

{
  "_metadata": 
  {
      "page": 5,
      "per_page": 20,
      "page_count": 20,
      "total_count": 521,
      "Links": [
        {"self": "/products?page=5&per_page=20"},
        {"first": "/products?page=0&per_page=20"},
        {"previous": "/products?page=4&per_page=20"},
        {"next": "/products?page=6&per_page=20"},
        {"last": "/products?page=26&per_page=20"},
      ]
  },
  "records": [
    {
      "id": 1,
      "name": "Widget #1",
      "uri": "/products/1"
    },
    {
      "id": 2,
      "name": "Widget #2",
      "uri": "/products/2"
    },
    {
      "id": 3,
      "name": "Widget #3",
      "uri": "/products/3"
    }
  ]
}

Lisibles par machine pour les métadonnées, je voudrais ajouter Lien des en-têtes à la réponse:

Link: </products?page=5&perPage=20>;rel=self,</products?page=0&perPage=20>;rel=first,</products?page=4&perPage=20>;rel=previous,</products?page=6&perPage=20>;rel=next,</products?page=26&perPage=20>;rel=last

(le Lien valeur d'en-tête doit être urlencoded)

...et peut-être une coutume total-count en-tête de réponse, si vous le souhaitez:

total-count: 521

L'autre pagination des données a révélé dans l'homme centrée sur les métadonnées peuvent être superflu, pour la machine, centrée sur les métadonnées, ainsi que le lien des en-têtes laissez-moi savoir à quelle page je suis sur et le nombre par page, et je peux rapidement récupérer le nombre d'enregistrements dans le tableau. Donc, je serais probablement seulement créer un en-tête pour le nombre total. Vous pouvez toujours changer d'avis plus tard et en rajouter.

Que d'un côté, vous remarquerez peut-être que j'ai supprimé /index de votre URI. Généralement, la convention est d'avoir votre point de terminaison ReST exposer des collections. Ayant /index à la fin brouille que légèrement.

Ce sont juste quelques choses, je tiens à avoir lors de la consommation d'/création d'une API. Espérons que ça aide!

Je recommande l'ajout d'en-têtes pour le même. Déplacement des métadonnées pour les en-têtes aide à se débarrasser de l'enveloppe comme result , data ou records et le corps de la réponse ne contient que les données dont nous avons besoin. Vous pouvez utiliser Lien en-tête si vous générez la pagination trop de liens.

    HTTP/1.1 200
    Pagination-Count: 100
    Pagination-Page: 5
    Pagination-Limit: 20
    Content-Type: application/json

    [
      {
        "id": 10,
        "name": "shirt",
        "color": "red",
        "price": "$23"
      },
      {
        "id": 11,
        "name": "shirt",
        "color": "blue",
        "price": "$25"
      }
    ]

Pour plus de détails, consultez:

https://github.com/adnan-kamili/rest-api-response-format

Pour swagger fichier:

https://github.com/adnan-kamili/swagger-response-template