2

I'm designing a Rest API for our web application.

There's one idea that came to my mind today and I haven't found in recent searches: a "hello" resource, where clients are supposed to connect as the first step; it should be like the "entrance" to the whole service.

The main reason is to have a defined point where I can attach server-side logging logic; it could tell the whole application state, so that clients do not try to access several other resources that would fail; theoretically it could return a reader token that allows requests toward resources to be successful for anonymous clients.

That's almost it, quite an initial shape of idea instead of a complete one, but the idea appeals to me.

What do you think about it?

5
  • 1
    Why is asking a question on “best practice” a bad thing?
    – user22815
    Commented Oct 29, 2015 at 17:58
  • @Snowman How's my question about a "best practice"? Where am I asking that?
    – watery
    Commented Oct 29, 2015 at 20:39
  • "I'm designing a Rest API, trying to follow common best practices like being HATEOAS, using HTTP verbs for actions, and so forth." also "Do you see any potential anti- best-practice here?"
    – user22815
    Commented Oct 29, 2015 at 20:40
  • As I supposed, you're really picking some words out of my question to state that it's about "best practices". The question is whether my single entry point resource could be a good idea or not: I'm going to edit it.
    – watery
    Commented Oct 29, 2015 at 20:44
  • that is better. Often the wording of a question can make it sound like something it is not, and attract close votes. It might sound silly, but a little extra effort when writing the question can be a big help.
    – user22815
    Commented Oct 29, 2015 at 20:49

2 Answers 2

1

Your question is complicate to answer, as a lot of persons doesn't agree about what is really a REST API. The only authorative - but unfortunately "too conceptual" - answer is the Roy Fielding's PhD thesis. So depending on your needs, you will adhere to different degree of the REST principles.

What is the requirements of your clients ? Do you need really to fulfill the 3 levels of maturity of REST ? Especially the third, that involve for a client to do more request to build its own application state (rather than "hardcoded" URIs that have also some benefits!)

Let's say, that you want to adhere strictly with REST following with verbs, resources and HATEOAS stuff. The first step is to create a main entry point that will be the starting point of your client. A client that retrieve this main entry point through a resource, will have some links that redirect to your differents resources (which resources you put depends on your software architecture!). Here, you will probably have a link to the hello resource.

I didn't get why you need a reader token, but token are a common practice to have a kind of "stateless" permission as your server doesn't store any information about the client, because the token is held by clients.

You should also note that if you start to deal with HATEOAS, it will requires to have hypermedia format. JSON is not an hypermedia format, there isn't any notion of links in this format. But it exists a lot of hypermedia format (Siren, HAL, Hydra, etc...) that have been proposed.

1

One of the characteristics of a RESTful API is HATEOAS (Hypertext as the engine of application state). HATEOAS implies that "a REST client enters a REST application through a simple fixed URL" (quoted from Wikipedia). So yes, it is common to REST APIs to have a resource that clients use as the first step.

HATEOAS aims at decoupling client and server. If there were multiple entry points, then the clients would not only have to know the URI of one entry point, but the URI of all entry points. It would not be possible to change these URIs without impacting the clients. If the user should be able to choose what to do first, then the API should offer a resource containing one link for every thing the user could do first. These URIs can then change without impacting the clients.

Furthermore, a single entry point allows us to enable/disable certain functionality server-side. The clients will not access resources when they don't have the corresponding links. You are probably referring to this benefit in your question ("clients do not try to access several other resources that would fail").

You could use the entry point also to initialize a session, at least that's what I understand from your question ("attach server-side logging logic" and "return a reader token"), but be careful that keeping server-side session information might be harmful for scaleability.

1
  • Maybe you should mention in first place, that by definition, a RESTful API does not implement sessions.
    – ClemC
    Commented Jun 28, 2019 at 11:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.