如何为 REST API 建模以设计计算器服务

Question

I have been reading about the best practices for designing API's for REST services that will be exposed to customers. For example, we should use Nouns to name all the URI's exposed. Further the verbs should obey the semantics of the HTTP commands. For example, a GET request should never modify the resource, instead PUT request should be used here. I was asked this question during an interview and couldn't answer this satisfactorily-- I am designing a calculator that provides following functions, add, multiply, divide, subtract on two operands. How do I expose these methods to clients following REST principles. What URI to use for these operations? And I am not sure whether to map an add operation to GET,PUT or POST. Same for the other operations (divide, multiply etc). What are the guidelines here ?

Answer 1

What are the guidelines here ?

How would you do it with a web site?

That should be your first heuristic any time somebody asks you about REST . REST is an
architectural style , designed for "long-lived network-based applications that span multiple organizations". The reference application for this architectural style is the World Wide Web.

I am designing a calculator that provides following functions, add, multiply, divide, subtract on two operands. How do I expose these methods to clients following REST principles.

There are three pieces of information that the client has, which need to be communicated to the server - the operation and the two operands. One the web, the usual way to collect that sort of information is to provide a form. In this case, it might be a dropdown list of operations, and a couple of text controls to accept numbers. Because a pure function is a safe , we would probably use GET as the form method. So the HTML processing rules would take the values described by the form and transcribe them as key value pairs in the query part.

So the url would look something like

/22520c7f-6207-490e-99c9-bd1bb37f4056?op=add&firstArg=6&secondArg=9

The key generalization is to realize that the HTML form is playing the role of a URI Template - the server passes the template to the client, the client fills in the details and uses the result as the target of the request.

What this implies is that if you wanted to replace HTML with some other media type, you would need to specify a description for URI Templates, some mechanism for describing the acceptable ranges and what values might be reasonable defaults.

What URI to use for these operations?

With REST? absolutely does not matter. That's part of the point -- the client treats URI as opaque values.

URI are just identifiers ; you can think of them like variable names in a program. The machines just don't care what the spellings are (so long as those spellings are consistent with RFC 3986).

Since the spelling doesn't matter, you can use whatever the local spelling conventions happen to be. A lot of people favor "hackable" URI -- the spelling of the identifier communicates useful information to the human reader.

URI are identifiers of resources ; "any information that can be named can be a resource". This motivates some of the "nouns not verbs" noise -- the resources are web pages, or documents, or images, or scripts, or ... the "resource" concept is deliberately vague, so that it can be used flexibly.

I am not sure whether to map an add operation to GET,PUT or POST.

The key is to look at the semantics of the client's request. Anytime what you are doing is a query/lookup, something that is OK for the machine to do automatically for the user, then you are looking at safe semantics, and the method is likely to be GET or HEAD (special circumstances).

If we were asking the server to change the representations of its own resources, then PUT and POST come into play.

In this case, all of these operations are just doing lookups, so GET is appropriate.

(An interesting thing to note is that the none of these operations depend on server state; they are pure functions. So it might make sense to serve the client with code on demand -- javascript or some reasonable replacement -- and use the client's processor to perform the calculations rather than doing a bunch of round trips across the network).

Answer 2

I think one issue with the term REST is that it can have a different meaning to different people. It's possible that the interviewer has a different understanding of REST. When something like this comes up, my first inclination is to try to figure out what REST means to them. Do they mean hypermedia? Do they care about the verbs and nouns being used correctly as you mentioned? Or is in their mind REST just some HTTP endpoint that returns JSON. All of these are possible.

I would be inclined to answer the question as follows I think:

GET /add/1/2
GET /multiply/5/6
etc..

Answer 3

Others with much more experience than myself have answered with examples of good ways to do this.

I'd just like to point out what a really excellent question this is. I'm reading a paper by Richard Taylor and others from UC Irvine. Richard Taylor was Roy Fielding's advisor back when Fielding described REST in his PhD thesis. In a discussion comparing REST and SOAP, the paper includes this:

"...the closer the service semantics are to those of content, the more likely the service is to have a rich REST API.

...

the division between REST and SOAP may reflect a lack of design guidance; how can services that are not content-centric, such as auction bidding ... be cleanly constructed in a REST-consistent manner?"

When they say "closer to content" they mean that the service looks more like some dynamic or static information to be retrieved by the end user, as opposed to a service looks like something that actively performs some function or calculation for the user.

They go on to provide additional guidance on this - but I haven't finished reading the paper yet, so I'll let you look that up for yourself. :-)

Search the web for: From Representations to Computations: The Evolution of Web Architectures, Richard N. Taylor, UCI