REST API Guideline

[stianst]

https://github.com/keycloak/keycloak-community/blob/master/design/rest-api-guideline.md

[stianst]

Documentation and Swagger/OpenAPI specifications are a critical component of a REST API. This section is missing even though it's probably one of the most imporant sections.

[stianst]

https://github.com/keycloak/keycloak-community/blob/master/design/rest-api-guideline.md#technology-preview

It states a preview API should follow:

/{realm}/apis/{API_GROUP}/{version}/preview/{preview_id}

It doesn't mention what preview_id is.

However, preview should be a function of the version and not add to the path. So it should be:

/{realm}/apis/{API_GROUP}/{version}preview

I.e.

/myrealm/apis/account/v1preview

[stianst]

https://github.com/keycloak/keycloak-community/blob/master/design/rest-api-guideline.md#pagination should have a pagination or last link so it's possible to know how many pages there are. Or, should pagination include the total count?

[akoserwal]

Total count for users, clients are often required not just for pagination. but keeping a track of the limitations

[akoserwal]

https://github.com/keycloak/keycloak-community/blob/master/design/rest-api-guideline.md#filtering

• Based on attributes or custom attributes (search by attributes: added already)
• Based on the client type. Eg: get all the client types: service accounts.
• Based on the regex. Eg: get all clients with pattern: client-<uuid>

[akoserwal]

Adding resourceVersion for https://github.com/keycloak/keycloak-community/blob/master/design/rest-api-guideline.md#concurrency-control-and-concurrency