CODEWITHSUNDEEP
rest
Shoreline
Shoreline

Reputation: 812

Which REST code for a resource which is conditionally available

I'm making a game where you can start a battle based on a task from a list.

Once you finish a battle (win or lose) the battle state will no longer be available, because there is no battle in progress.

This will be reflected in the API when you GET /battle.

My question is as follows: What REST code should I use to express that the battle is not currently available.

Additional:

Upvotes: 1

Views: 39

Answers (1)

Jesse Squire
Jesse Squire

Reputation: 7745

Under the constraint of using a unique response code to indicate the result, I would opt for an HTTP 204 (No Content). My rationale is that what you're looking to do is indicate that the resource (your battle) is valid, but there is currently no data available for it.

You could also opt to go HTTP 200 (Ok) and return a payload that indicates the current state, both when a battle is in progress and when it is not. This is what I'd probably go for, personally, as it helps to normalize the shape of your API for callers. Instead of callers having to memorize the rules around return code, they receive the same data structure in both scenarios and interpret it to discern the context. This would also allow you to extend the API with historical data, such as battle stats, after the battle was completed without breaking changes to the API.

I'm thinking something like the following for an in-progress:

{
    "Id"         : 1234,
    "InProgress" : true,
    "Battle      :
    {
        "SomeProp"  : "SomeValue",
        "OtherProp" : "OtherValue"
    }
}

...and something like the following for one not in-progress:

{
    "Id"         : 1234,
    "InProgress" : false,
    "Battle      : null
}

I believe both approaches would be considered appropriate RESTful responses. To me, the choice is personal preference for the API contract that you'd like to offer.

Upvotes: 1

Related Questions