Designing the Right REST URIs

Question

I have a Java component that scans a set of folders (input / processing / output) and returns a list of files in JSON format.

REST url for it:

GET http://<baseurl>/files/<foldername> 

Now I need to perform certain actions on each of the files, for example, check, process, delete, etc. I'm not sure if you can create a REST URL for these actions. Since it has direct file manipulation, I do not have a unique identifier for files other than their paths. So I'm not sure if the following url is a good one:

 POST http://<baseurl>/file/validate?path=<filepath> 

Edit: I would ideally enjoy using something like the file / file / fileId / validate. But the only unique identifier for files is its path, and I don't think I can use it as part of the URL itself.

And finally, I'm not sure which HTTP verb to use for user actions like validate.

Thanks in advance!

Regards, Anand

Answer 1

When implementing a route, such as http: /// file / validate? Path , you encode the action in your resource, which is not a desirable effect when modeling the resource service.

You can do the following for read operations

GET http://api.example.com/files will return all files as a URL link, e.g.

 http://api.example.com/files/path/to/first http://api.example.com/files/path/to/second ... 

GET http://api.example.com/files/path/to/first will return validation results for the file (I am reading JSON for reading)

 { name : first, valid : true } 

It was an easy part to read. Now for write operations:

DELETE http://api.example.com/files/path/to/first , of course, will delete the file

Modeling file processing is the hard part. But you could model this as a top-level resource. So that:

POST http://api.example.com/FileOperation?operation=somethingweird will create a resource for processing virtual files and perform the operation specified by the URL parameter 'operation'. Modeling these file operations as resources enables you to perform asynchronous operations and return a result that provides additional information about the operation process, etc.

You can take a look at the Amazon S3 REST API for additional examples and inspiration on how to model resources. I can highly recommend reading RESTful Web Services

Answer 2

Now I need to perform certain actions on each of the files, for example, check, process, delete, etc. I'm not sure if you can create a REST URL for these actions. Since it has direct file manipulation, I have no unique identifiers for files other than their paths. So I'm not sure the following is a good URL: POST http:///file/validate?path=

This is not true. /file/validate does not describe the resource; it describes the action. This means that it is functional and not RESTful.

Edit: I would ideally like using something like /file/fileId/validate . But the only unique identifier for files is its path, and I don't think I can use it as part of the URL itself.

Oh yes you can! And you must do just that. Except for this final part, validate ; it is not a resource, and therefore it should not be part of the path. Instead, clients should send a message to a file, requesting it for verification. Fortunately, POST allows you to send a message to a file, as well as receive back; it is ideal for this kind of thing (if instead there is no existing verb, whether in standard HTTP or one of the extensions such as WebDAV).

And finally, I'm not sure which HTTP verb to use for user actions like validate.

POST, with the action to be performed, determined by the content of the message that was sent to the resource. Custom actions to "do something non-standard" are always mapped to POST when they cannot be mapped to GET, PUT or DELETE. (Alas, smart POST is not extremely affordable and therefore causes problems for the HATEOAS principle, but it is still better than violating the basic principles of REST.)

Answer 3

REST requires a uniform interface, which in HTTP means restricting itself to GET, PUT, POST, DELETE, HEAD, etc.

One of the ways to check the correctness of each file in RESTful is to check the validation not as an action to execute in the file, but as an independent resource:

 GET /file/{file-id}/validity 

This can lead to a simple True / False or possibly a list of specific constraint violations. A file identifier can be a file name, an integer file number, a URL-encoded path, or possibly an uncoded path, for example:

 GET /file/bob/dir1/dir2/somefile/validity 

Another approach would be to request a list of invalid files:

 GET /file/invalid 

Nevertheless, it will prevent others from adding incorrect files to your service, first of all, i.e. when your service processes a PUT request with bad data:

 PUT /file/{file-id} 

he rejects it using HTTP 400 (Bad Request). The response body 400 may contain information about a specific error.

Update. To delete a file, you will of course use the standard HTTP REST verb:

 DELETE /file/{file-id} 

To process a file, does it create a new file (resource) from the downloaded one? For example, Flickr creates several different image files from each uploaded one, each with a different size. In this case, you can CALL the input file, and then initiate processing with the GET file of the corresponding output file:

 PUT /file/input/{file-id} GET /file/output/{file-id} 

If the processing is not nearly instantaneous, you can generate the output files asynchronously: every time a new input PUT file in the web service, the web service starts asynchronous activity, which ultimately leads to the output file being created.