Multiple optional query string parameters REST API GET

ぐ巨炮叔叔 提交于 2019-12-01 16:09:32

You don't want option (2) - to be RESTful you want nouns in your URL.

So you want your URL's to look like:

/api/items/?crewId=1234&shiftDate=1111-11-11

(I can't work out what your Items are, based on the 'Crew' and 'Shift' parameter names. What has a Crew and a Shift date?? Fishing trips?? If so, the url would be better as /api/fishing-trips/?crewId=....&shiftDate=...

As for the controller, I'd go for something like:

public HttpResponseMessage Get(string crewId = null, string shiftDate = null, int offset = 1, int limit = 10) {

    return dataSource.Where(x=> (x.CrewId == crewId || crewId == null)
            && (x.ShiftDate == shiftDate || shiftDate == null));
}
McArthey

Reviewing Best Practices: Understanding REST Headers and Parameters it states that the use of the query parameter would indicate that it is optional. If you can make a single value required and the others optional it might help clarify the URI.

/api/fishing-trips/crew/{crewid}?shiftdate=1111-11-11

In the end if your items are all optional then use of the "?" is probably the best route. Further information on types of parameters are available at RFC 6570.

Note that your choice may have impact on any queueing that you choose to use and the path-style parameter expansion may make the most sense. More information also at Understanding REST Parameters.

Lastly you may wish to create these as search parameters then, if you find that your users are often requesting the same search, you can package it into a single REST path.

For example,

/api/fishing-trips/search?crew=1234
/api/fishing-trips/search?shiftDate=1111-11-11
/api/fishing-trips/search?crew=1234&shiftDate=1111-11-11

You could also provide a simplification along with optional parameters, for example,

/api/fishing-trips/today
/api/fishing-trips/today?crew=1234
/api/fishing-trips/crew/1234/today

These last examples are subjective from my research but more information is available at Best Practices for a Pragmatic Rest API and RESTful URL design for search.

I've done something like this before. Since you can use one or the other or both, I would use the optional parameters:

public HttpResponseMessage Get(string crewId = null, string shiftDate = null, int offset = 1, int limit = 10)

Then construct your query. For example, something like this:

var query = "";
if (!String.IsNullOrEmpty(crewId)) {
  query += $"crewId='{crewId}'";
}
if (!String.IsNullOrEmpty(shiftDate)) {
  if (query.Length > 0) query += " AND ";
  query += $"shiftDate='{shiftDate}'";
}
if (query.Length == 0) {
  //neither crewId or shiftDate were given
  //return some kind of error
}

Considering that I am about to implement this myself, I will say it should be a single GET method action with multiple optional parameters.

Why? Because you should not worry about this querying logic in the REST API layer. After all, you are effectively creating an AND discrimination clause with multiple parameters (i.e. CrewId = 1 AND ShiftDate = 2016-01-01). And if you don't supply parameters, return all the items.

I will be passing my parameters all the way through to a SQL stored procedure which has default values specified and will return the results based on the parameters passed.

Remember that in many ways, REST methods map directly to CRUD, so treat your API as such: REST API Tutorial

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!