We have one feature in our REST API which could have a reason to be shutdown temporarily, or permanently. Let's say the resource is:


Right now, /needs_shutdown is a GET request that returns data. We want to make returning data happen only if the service is marked as active in our configuration.

So, how do we implement the response? The response could be one of two things:

Service is active, meaning they get data that fits a NeedsShutdown object:

    here: "is",
    some: "data",

or service is inactive, and the response data would fit some kind of Error object:

    error: "Service is unavailable",
    code: 123456789,
    other: "important data"

So the client would expect either a NeedsShutdown object, or an Error object. Specifically we're using Android (Java) with the Retrofit library, if that makes a difference in the design possibilities.

How should we design this REST endpoint to have this kind of optional behavior?

  • What about inheritance? NeedShutdown and Error extends/implements ApiResponse. Finally force endpoints to return ApiResponse instead of an specific response type. I know some more approachs but all of them tied to Spring Framework. Just a question. Does these two responses cause Http status 200? For the error you are encosing there's an Http status. – Laiv Aug 31 '16 at 20:14
  • The Http status I was refering to is 503. – Laiv Aug 31 '16 at 20:21
  • 1
    503 is the right one developer.mozilla.org/en-US/docs/Web/HTTP/Status/503 and check retry after which may prevent clients from keeping trying. When your service stops finally and never comes back you send 404. – Luc Franken Sep 1 '16 at 8:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.