CODEWITHSUNDEEP
rest
tony
tony

Reputation: 2392

REST API on files

I'm trying to get an understanding of REST

You have a web server which allows operations on files, you can copy, print, merge, translate, delete, etc files (so, basically a whole bunch of verbs on the noun)

How does this translate into REST?

Can all/most RPC type interfaces be mapped to REST?

Upvotes: 0

Views: 64

Answers (2)

Jesse Squire
Jesse Squire

Reputation: 7745

The basic gist of REST is to provide a guideline for interacting with resources in a common way, in order to make discovery and interaction easier for callers. This is done by mapping logical API concepts to HTTP concepts.

At its heart, REST is all about resources. So, what's a resource? In a nutshell, it is a thing - a noun. Each resource should be represented by a unique URI, and each URI should represent one unique resource. This will typically follow the pattern of root/collection/item where that may sometimes repeat. For example: api.halo.com/players/SomeGuy/matches/1234. In the example, the noun, is a match that was played by a specific player. To reference it, we start at the root (api.halo.com) and go through the collection of players to reach the player named SomeGuy and then through the collection of matches that he/she played to get to the specific match (1234) that we're interested in.

Now that we have a resource, we want to do some things with that resource, such as look at it, replace the entire thing with a new one, update some properties of it, or maybe create a new resource. REST makes use of HTTP verbs to express the operation that you'd like to perform. For example, GET is used to indicate "hey, please give me this thing", POST indicates "hey, please create me a new thing", PUT indicates "please take my new thing and replace the thing you have with it", PATCH indicates "please update some of the properties of the thing with my new data", and DELETE indicates "please remove this thing.

In general, interfaces that deal with a single "thing" or a collection of a single type of "thing" are the ones that map most cleanly to RESTful design. That said, if you're creative enough, you can usually find a RESTful way to model just about all of the concepts that you'd be making RPC calls for, though tuning your API patterns to concentrate on resources and data will help a lot there.

One final call-out that I should make is that you're likely to find that there are many, many strong opinions on REST in the community. There are those that are very pedantic, black-and-white, about what qualifies as RESTful and what doesn't - and different schools of thought on what that is. There are just as many individuals that are apt to relax some of the concepts when needed but still consider their design RESTful.

My very general advice would be to concentrate on who the consumers of your API are and design something that helps them fall into the pit of success - doing the obvious thing and following well-established guidelines where possible, but making things as obvious and easy for them as you can when it doesn't line up so clean.

Here's a couple of things that may offer more introductory context:

Upvotes: 0

Jochen Bedersdorfer
Jochen Bedersdorfer

Reputation: 4122

As long as you think of your data as a collection of resources that can be manipulated with GET, DELETE, POST, PUT, then yes.

It might require you to add more 'nouns' though. You could treat some of these operations as their own resource. For example, a POST to /myfile/copy would return a Location header with the URL of the new copy: /myfile(2) or something like that.

A process like printing could look like this:

POST the print config to /myfile/prints which would create a print job resource: /myfile/prints/12345

a GET on /myfile/prints/12345 would give you the status of the print job. a DELETE on /myfile/prints/12345 would stop the print job

Upvotes: 1

Related Questions