Make authorization model endpoints HATEOAS / HAL compliant

[geoffroybraun]

Nowadays, we can retrieve all authorization models by calling the endpoint /stores/{store_id}/authorization-models, which allows us to specify how many items we want per page using the query parameter page_size. Unfortunatly, only a continuation_token is retrieved, which can not indicate how many authorization models can still be retrieved, forcing us to call the same endpoint again and again until recieving less ahtorization models than specified in the query or checking if a token has been provided.

A successful solution would be to use HATEOAS HAL specification.

With that, the endpoint could retrieve authorization models with pagination links calculated on the fly depending on how many models are currently stored in the database, but also links related to the model itself within the object. Here is an example when calling /stores/{store_id}/authorization_models with page_size=1 and page_index=2:

{
   "items":[
      {
         "id":"{authorization_model_id}",
         "_links":{
            "self":{
               "href":"/stores/{store_id}/authorization-models/{authorization_model_id}",
               "method":"GET"
            }
         }
      }
   ],
   "total":5,
   "_links":{
      "self":{
         "href":"/stores/{store_id}/authorization-models?page_size=1&page_index=2",
         "method":"GET"
      },
      "first":{
         "href":"/stores/{store_id}/authorization-models?page_size=1&page_index=1",
         "method":"GET"
      },
      "prev":{
         "href":"/stores/{store_id}/authorization-models?page_size=1&page_index=1",
         "method":"GET"
      },
      "next":{
         "href":"/stores/{store_id}/authorization-models?page_size=1&page_index=3",
         "method":"GET"
      },
      "last":{
         "href":"/stores/{store_id}/authorization-models?page_size=1&page_index=5",
         "method":"GET"
      },
      "create":{
         "href":"/stores/{store_id}/authorization-models",
         "method":"POST"
      }
   }
}

In the example above, the links self, first, last and create are permanent, while prev and next are optional, depending on the current page index and authorization models count. With that, it would be much easier for an API consumer to navigate thouth all available authorization models, as everything would be provided by the API itself.

As usual, let me know if further information are required. Cheers!

[rhamzeh]

Hey @geoffroybraun - thanks for the suggestion.

We will take that into consideration.

However in regards to your use case:
The latest model is always the first model returned (they are sorted by descending date created)

Our SDKs try to be helpful and expose a method called ReadLatestAuthorizationModel, but all it does is just call ReadAuthorizationModels with pageSize=1.

Do you have a use-case in mind where you would need a particular model but don't know it's ID and it's not latest, but you know the page number?