9

I am using web api 2 to implement a restful service. After doing some research on best practices everyone seems like they are having different opinions on how to do the following. I have a GET

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

This GET method returns a list. There are multiple ways of getting the data from this method.

  • Get by crewId only
  • Get by shiftDate only
  • or
  • Get by crewId and shiftDate
  • Do you (1) Mark the crewId and shiftDate as optional?

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

    and then have bunch of if statements to check what is filled and what is not filled to be able to do actions

    if(crewId != null && shiftDate == null){
      // Get by crewId
    }else if(crewId == null && shiftDate != null){
      // Get By shiftDate
    }else if(crewId != null && shiftDate != null){
      // Get By crewId and shiftDate
    }
    

    To me this looks crazy to do especially if you have many parameters you would have too many "if" statements in your code.

    Do you (2) Have different set of gets?

    public HttpResponseMessage GetByCrewId(string crewId, int offset = 1, int limit = 10)
    public HttpResponseMessage GetByShiftDate(string shiftDate, int offset = 1, int limit = 10)
    public HttpResponseMessage GetByCrewIdShiftDate(string crewId, string shiftDate, int offset = 1, int limit = 10)
    

    and then you would have your URI Route map to the method

  • .../api/GetByCrewId?crewId=1234
  • .../api/GetByShiftDate?shiftDate=1111-11-11
  • .../api/GetByCrewIdShiftDate?crewId=1234&shiftDate=1111-11-11
  • is option 2 restful?

    Or is there an better options (3).

    Both options above will work just making sure I am using best practices and following REST standards. Just seems like I am missing something and hopefully you can put me in the right direction.

    4 Answers 4

    7

    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));
    }
    
    4
    • Thanks for the answer @Anthony - The only thing I believe you would still have to have if statements because I don't even want to query the database for crewId of shiftDate if one is null - Because If I do what you have above it will look where the shiftDate or crewId is null and return wrong set of data. But all in all the concept of the GET is the same what I have currently just have a hard time agreeing to it. Jan 19, 2016 at 17:11
    • The controller method does what you say. Take the first line for example: x.CrewId == crewId || crewId == null . If crewId is null, the statement resolves true and the record would be permitted to test the shiftDate. If that's also null, then the shiftDate statement would resolve true and the record would be returned.
      – Anthony
      Jan 19, 2016 at 17:14
    • I see never mind - my mistake I glanced really fast over the linq statement i thought you had x.CrewId == null. You are absolutely right. Jan 19, 2016 at 17:18
    • Easy to miss with just a glance
      – Anthony
      Jan 19, 2016 at 17:24
    7

    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.

    2

    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
    }
    
    2
    • Thanks Gabriel Luci for Answering. That is what I currently have is GET with optional parameters but just have a hard time wrapping my head around that I would have to have if statements for every possibly outcome. If I had n parameters I would have n possibilities which is just crazy but probably the right way that I just cant agree with my self :) Jan 19, 2016 at 17:13
    • There will likely be some logic that is common no matter which identifiers are used to do the search (for example, you always look for "enabled" records, or something like that). So duplicating that logic in multiple controllers is probably not a good idea. Jan 19, 2016 at 18:25
    1

    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

    Your Answer

    By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

    Not the answer you're looking for? Browse other questions tagged or ask your own question.