API Listing

[Ron R]

Hi everyone,

After chatting with Tony on IRC for a while, I've decided to take some of the questions offline so that they'll be available to everyone to view.
I'll try to split the questions into several topics so they won't clutter each other.

First thing's first - the API Listing.
Today, after a long time, I finally understood that besides the 'root' of the API Listing <host>/resources - all other resource listings are based on @Path annotations of the classes. Since the API Listing works with GET as well, if the top-level @Path has a @GET request, they'd conflict.

In order to resolve that, there's a nice solution of creating a helper class that holds the root path API listing, and it can be linked to via the root class.
While this is a useable solution, I feel that it can make code maintenance a bit of a pain, especially for a large API code base.

In our code base, we have roughly 40 REST API classes. If I'm not mistaken, most if not all have a GET operation on their roots.
Creating additional 40 helper classes seems like a huge overhead.

So in turn, I ask:

1. Shouldn't the API listing use /resources as a base for all the listings? Conflicts can and will occur if the API listing is equivalent to the @Path usage. GET operations are especially common as well. Why not have a 'copy' of the REST calls under another level of hierarchy that's specifically used for the listing? I think that it should at least be configurable to be able to do that by default in order to help complex APIs.
2. Another possible solution is to return the API listing response using the OPTIONS HTTP method. I'm no expert when it comes to REST and HTTP standards, but from what I can tell, OPTIONS is meant to be used for API listing in a way. I also doubt that many REST APIs out there use the OPTIONS call themselves - I imagine GET/POST/PUT/DELETE are far more common.

Thoughts?

[tony tam]

Howdy Ron, some thoughts.

1) One can definitely argue for a different resource listing path (/resources.json/pet instead of /pet.json, for example).  As you mentioned this is supported in the framework but not super convenient.  I'd propose that we just make it easy to configure that instead of changing the default behavior.  Definitely a good point on that front.

I do think however, that you can stuff all the helper paths in a *single* class (you'll have 40 methods but not 40 classes).  I think that would ease the pain but not make it go away.

2) Right you are about the OPTIONS.  Not widely used and hard to manually inspect.  I do think though that swagger could support sending the spec on that request without much work.  Then you don't *lose* an api path to /resources.json/pet for instance.

Tony

[Ron R]

1) I completely agree regarding the option to make it configurable. The default behavior doesn't matter much as long as there's a way to configure it to a different behavior. Obviously, the more widespread the usage of the project, the less you'd want to make changes that break the current behavior.
Regarding the single class, I hadn't realized that that was a possibility. It would definitely ease development and allow me to move forward with implementing Swagger in our application.

2) Just another aspect, since I'm not a JS developer and have very limited knowledge in the matter. Will the Swagger-UI be able to work if the HTTP ingestion method is OPTIONS?