Does this implement a RESTFUL API?

Question

This might seem like a strange question but I wanted to get the opinion of some other developers out there. This has come up with some potential patent issues we might be facing.

I have a electronic device out on the Internet (installed at customer site) that polls our server every T seconds. Each device has a unique serial number and the URL each device polls is unique (based on the serial number on the end of the URL):

Poll every T seconds:

http://example.com/device/SERIAL_NUMBER

Our server just returns a "0" or a "1". Literally, if you hit the URL you will see a 0 or 1 in the browser.

This "0" or "1" just tells our device to turn on and turn off. Essentially it's a remote "switch" to turn a device on and off. When we return 0, go off, when we return 1, go on.

No JSON, no XML, just a 0 or 1.

Would this be considered, in the purest/simplest form, in any way a "RESTFUL API".

My thought is "no", we are just using HTTP to poll a unique URL and returning a binary on/off -- whereas it seems in order to have a RESTFUL API you would need to have more than just hitting a URL and returning a bit.

Thanks!

Answer 1

Would this be considered, in the purest/simplest form, in any way a "RESTFUL API".

tl;dr

Technically no. Legally is a different matter. Where there are laywers there are ways. IANAL.

Rationale

The problem with the terms REST and RESTful is that their definition is abstract and rightly so, because REST defines an architectural pattern, not a detailed specification. According to Roy Fielding, who coined the term, REST is defined by several properties and constraints.

Thus in order to answer your question we need to understand what is generally considered a RESTful system. Then we can assess whether your system matches this definition.

Definition

Properties

Properties are exhibited, observeable effects of the system's architecture. The properties are a result of the system's architecture, design and implementation, and a RESTful system is typically expected to achieve at least the majority of these properties. I would argue, however, that the mere presence of these properties is not as such an indication of a system's "RESTfulness" as there are other ways to achieve them.

• Performance - component interactions can be the dominant factor in user-perceived performance and network efficiency
• Scalability to support large numbers of components and interactions among components.
• Simplicity of a Uniform Interface
• Modifiability of components to meet changing needs (even while the application is running)
• Visibility of communication between components by service agents
• Portability of components by moving program code with the data
• Reliability is the resistance to failure at the system level in the presence of failures within components, connectors, or data

Source: Wikipedia

Constraints

Constraints are defining (necessary and sufficient) elements of a system's architecture. If a system violates any of these constraints it cannot by definition be considered a REST system. Thus constraints are a much stronger indication of a system's RESTfulness.

• Client Server - (...) Separation of concerns is the principle behind the client-server constraints (...)
• Stateless - The client–server communication is constrained by no client context being stored on the server between requests.
• Cacheable - As on the World Wide Web, clients and intermediaries can cache responses.
• Layered system - A client cannot ordinarily tell whether it is connected directly to the end server (...)
• Code on demand (optional) - Servers can temporarily extend or customize the functionality of a client by the transfer of executable code.
• Uniform interface - Identification of resources, Manipulation of resources through representations, Self-descriptive messages, Hypermedia as the engine of application state

Source: Wikipedia

Assessment

Properties

• Performance - YES, in general sense, your system's performance depends on the network performance (bad network performance means devices switch on/off with a delay, or not at all).
• Scalability - YES, clearly your system is scalable to an arbitrary number of devices, noteably without impact on the devices themselves.
• Simplicity of a Uniform Interface - YES, each device's URI
• Modifiability - YES, both devices and servers can be changed without the other being affected
• Visibility - YES, clearly communication is visible, at least at some level
• Portability - YES, the 0/1 instruction quite clearly is executable code (the device's state machine takes this as an event that leads it to effect an action, namely to switch off or on)
• Reliability - MAYBE, we don't know enough about your system

Conclusion: Your system exhibits most properties of a RESTful design. That's a necessary but not a sufficient indication of it actually being RESTful. So let's examine contraints next:

Constraints

• Client Server - YES, clearly this is a client-server design, and concerns are separated (server: schedule on/off per each device, device: effect on/off action)
• Stateless - YES, there is no client context stored on the server. Note this referes to the communication state, not the device state.
• Cacheable - YES, this is inherent in using http as the communications protocol
• Layered system - YES, this is inherent in using http as the communications protocol
• Code on demand (optional) - YES, as argued above, the 0/1 instruction can actually be considered executable code.
• Uniform interface - NO, resources are clearly identified, however manipulation is not possible, and there is no hypermedia present that would a client allow navigation of resources.

Conclusion: Your system as described does not fulfill all the constraints of the REST architectural state. Namely the uniform interface does not match the required extent - while it provides a uniform addressing scheme (the URI), it does not meet the other elements of a REST uniform interface.

Conclusion

Within the description of your system, while the use of HTTP as a protocol and a unique URI per each device indeed effects most of the necessary properties of a RESTful system, this alone is not sufficient for it to be considered RESTful as not all required constraints are met.

Answer 2

It's not even necessary to send "a bit."

Github API

Response if this repository is starred by you

GET /user/starred/:owner/:repo
Status: 204 No Content

Response if this repository is not starred by you

GET /user/starred/:owner/:repo
Status: 404 Not Found

That said, as a REST api it's not a very interesting one, as it implies that this particular application state is an end state in your protocol -- there are no links in the representation acting as affordances to further progress.

From Fielding's dissertation

REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.