1

I want to implement a REST API (for a video game on this example), and want to make it as stateless as possible (authentication would be the only state).

I am still quite confuse about what stateless truly means: for instance, 2 consecutive calls to 

api.myhost.com/users/{playerid}

can provide 2 different answers in time, for instance:

{name: "toto", life: 98, score: 52}

and

{name: "toto", life: 12, score: 378}

Questions:

  • Is providing a different answer when accessing the same resource considered breaking the stateless condition of REST API?
  • Is bending the rule in that case (influence of time on a resource) considered an accepted practice?
  • If not, as the reality I want to represent has a state (changing over time), how am I supposed to translate it into a stateless model ?
Pierre-Jean
  • 1,522
  • 12
  • 19

2 Answers2

3

What you describe - an API returning a different value over time - is perfectly fine. It's not what "stateless" is referring to.

"Stateless" means that each REST call should be self-contained: the server doesn't store any (or, much) information about the client. The client's state - for example, what page of a search result they were on, or whether they are logged in - isn't stored on the server; the client has to re-send it every time it makes a new request.

Here is a much more in-depth answer to a related question.

Community
  • 1
  • 1
Pekka
  • 418,526
  • 129
  • 929
  • 1,058
2

REST is stateless

REST stands for Representational State Transfer and this architecture was defined by Roy Thomas Fielding in the chapter 5 of his dissertation.

Fielding defined a set of constraints for the REST architecture. One of these constraints is the stateless communication between client and server, defined as following (the highlights are not present in his dissertation):

5.1.3 Stateless

[...] each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client. [...]

So, if you keep the session state on the server, you break the stateless constraint. Hence, it's not REST. In REST you won't have a session on the server and, consequently, you won't have session identifiers.

Each request must contain all data to be processed

Each request from client to server must contain all of the necessary information to be understood by the server. With it, you are not depending on any session context stored on the server.

When accessing protected resources that require authentication, for example, each request must contain all necessary data to be properly authenticated/authorized. It means the authentication will be performed for each request.

Resources can be static or can change over time

According to Fielding, resources can be static or they can change over time. Have a look at his dissertation:

5.2.1.1 Resources and Resource Identifiers

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.

More precisely, a resource R is a temporally varying membership function MR(t), which for time t maps to a set of entities, or values, which are equivalent. The values in the set may be resource representations and/or resource identifiers. A resource can map to the empty set, which allows references to be made to a concept before any realization of that concept exists -- a notion that was foreign to most hypertext systems prior to the Web. Some resources are static in the sense that, when examined at any time after their creation, they always correspond to the same value set. Others have a high degree of variance in their value over time. The only thing that is required to be static for a resource is the semantics of the mapping, since the semantics is what distinguishes one resource from another.

For example, the "authors' preferred version" of an academic paper is a mapping whose value changes over time, whereas a mapping to "the paper published in the proceedings of conference X" is static. These are two distinct resources, even if they both map to the same value at some point in time. The distinction is necessary so that both resources can be identified and referenced independently. A similar example from software engineering is the separate identification of a version-controlled source code file when referring to the "latest revision", "revision number 1.2.7", or "revision included with the Orange release." [...]

cassiomolin
  • 101,346
  • 24
  • 214
  • 283