Search code examples
apirestspring-mvcrestful-urlrestful-architecture

How to design RESTful URL with many input parameters

I am working to create a Java based RESTful API that uses Spring MVC.

Now for some of the API endpoints-- multiple different parameters are required... I am not talking about a list of values-- more like parameter1, parameter2, parameter3, parameter4 and so on-- where all the 4 (or more) parameters are of different data types as well.

How do I design the API endpoint URL for the above scenario, eg for 4 separate input parameters? Is there any recommended way/best practice for doing this? Or do I simply concatenate the 4 values, with ach pair of values separated by a delimiter like "/"?

EDIT from user comment:

Example: I have to retrieve a custom object(a 'file') based on 4 input parameters--(Integer) userid, (Integer) fileid, (String) type, and (String) usertype. Should I simply create a REST Endpoint like "getfile/{userid}/{fileid}/{type}/{usertype}-- or is there a better (or recommended way) to construct such REST endpoints?

Solution

  • In REST start by thinking about the resource and coming up with immutable permalinks (doesn't change)to identify that resource.

    So, in your example (in comment), you said you want to retrieve a file resource for a user and type (file type or user type?)

    So, start with just enough information to identify the resource. If the id is unique, then this is enough to identify the resource regardless of the user who owns the file:

    /files/{fileId}

    That's also important as the url if a file could change owners - remember we want to identify the resource with just the components needed so it can be a permalink.

    You could also list the files for a specific user:

    /users/{userId}/files/

    The response would contain a list of files and each of those items in the list would contain links to the files (/files/{fileId})

    If for some reason the file id is not unique but is unique only in the context of a user (files don't change owners and id increments within a user - wierd) then you would need these components to identify the resource:

    /users/{userId}/files/{fileId}

    Also note the order based on the description. In that wierd case, we said the files are logically contained and IDed by the user and that's also the containment in the url structure.

    Hope that helps.