Lock-in URL scheme for the HTTP API about blpapi-http HOT 11 CLOSED

#64 raises an interesting question: should we just put the "Request" back into the URL? It'll simplify the mapping there.

from blpapi-http.

I think that makes sense now that we have a better understanding of all the services, request, and events.

from blpapi-http.

Are we heading toward just appending "Request" at the end of the URL as in:
https://http-api.openbloomberg.com/request/blp/refdata/ReferenceDataRequest
or also remove the "request" in the middle as in:
https://http-api.openbloomberg.com/blp/refdata/ReferenceDataRequest

Also there are inconsistencies in the casing of the actual BLPAPI request names. First letter is lower case for some and upper case for others. That is slightly ugly and confusing. Do we want the real request name in the URL or should we have consistent casing in the URL and then map to real request name?
in other words:
.../blp/instruments/instrumentListRequest
or
.../blp/instruments/InstrumentListRequest

from blpapi-http.

We basically have five things: subscribe, unsubscribe, poll, request, and authorize. This can be further categorized as really three "kinds" of things: subscription related stuff, request/response related stuff, and auth/identity related stuff.

Some options (top level note: the exact strings may change, e.g. /request is probably the wrong text, so let's not get too hung up on those while discussing this):

1. Have a top-level route for each of the five things: /subscribe, /poll, /unsubscribe, /request, /authorize. This is nice in that it's very simple, but it'd be nice to group the three subscription related things together, and it's a bit unappealing to have the paths be verbs rather than resources.

2. Have a top-level route for each kind of thing: /realtime, /request, /auth. This makes the paths more resource-like, e.g. we're accessing the realtime resource of the HTTP service, and we use the query string (or the POST I guess, but I think we generally agree that query string is the way to go).

Re: query strings vs. POST: I think it's weird to mix query strings and POST data for the same request, but it's a lot simpler in some regards, and to be honest, we're basically just using POST to get around the size limit of URLs, and conceptually I'd probably just put everything in the query string if it were possible. It sounded like we all agreed with this, but wanted to write it down to verify.

from blpapi-http.

So, concretely, here are some URLs that we'd have in each scheme:

/subscribe
/poll?pollid=1
/unsubscribe
/request?service=//blp/refdata&type=HistoricalDataRequest
/authorize

/realtime?action=subscribe
/realtime?action=poll&pollid=1
/realtime?action=unsubscribe
/request?service=//blp/refdata&type=HistoricalDataRequest
/auth

from blpapi-http.

+1 for scheme 2

from blpapi-http.

Can the service prefix be anything else than "//blp"?

from blpapi-http.

3. Here's my attempt for RESTful api

• Request/Response(exception of using GET with body)

GET /data/refdata/historicaldata

• Subscription

subscribe all: POST /subscriptions
poll all: GET /subscriptions?seq=1
unsubscribe all:  DELETE /subscriptions
unsubscribe one: DELETE /subscription /1

• Authorization

authorize: POST /identify

from blpapi-http.

@thmiceli Currently all services are in the blp namespace, and I don't believe any will get introduced any time soon (probably ever). However, we should probably still retain it, just to be consistent with the BLPAPI (and also because it would majorly suck if someone, some day, decided they want to add such a namespace).

from blpapi-http.

We decided on option (2) to move forward with, but need to decide on the proper naming of the resources.

from blpapi-http.

Refinement of option 2 that I'm using: polling doesn't need an action, because GET /realtime implies you're polling.

I could also have POST /realtime without an action implicitly mean that you're subscribing but for implementation simplicity I'm requiring the action for both subscribe and unsubscribe for now.

from blpapi-http.