How to expose enum values in a REST API

Question

In a mobility context of use of the API, an advanced research proposes several dynamic filters that must be returned by the server. (We don't want to make too many exchange with server to initialize our filters)

In a REST api, how to expose a enum of possible values ​​for filter search?

Thank you for your suggestions/ideas?

Answer 1

My initial thought would be to treat the search like a normal resource. In an object oriented perspective, a search can have a collection of fields which can be used to filter by. These fields can be numeric, boolean, string based, or whatever.

So, if I understand your question correctly, then I would propose doing this:

GET /search_fields

If your API have multiple type searches that can be performed, then they can be identified by an id or maybe their name, as long as it is unique, like so:

GET /searches/{search_id}/fields

which would return a collection of search fields like so:

[{
  name: 'Field1',
  type: 'boolean'
},
{
  name: 'Field2',
  type: 'number'
},
{
  name: 'Field3',
  type: 'string'
}]

or if your fields are really just simple enums then:

[{
  name: 'Field1',
  id: 1
},
{
  name: 'Field2',
  id: 2
},
{
  name: 'Field3',
  id: 3
}]

That's my suggestion. Remember, there's no one right way to expose an API.