api-blueprint
api-blueprint copied to clipboard
apiaryio
Multiple hosts or subdomains
I was wondering if it's currently possible to document an API where requests can come in from different subdomains, but this subdomain changes the endpoints that are available?
As an example, users can either be organisation, or office users. Each organisation and office has it's own subdomain. If I request things as an organisation, I want only certain office related endpoints to be made available. If I make requests through an office subdomain, then the rest of the API opens up.
How would I model this with API-Blueprint?
Hey @pareeohnos, this seems like a task for an authentication / scoping and as such is probably best to resort to some sort of authentication (most likely header-based).
If I understand you correctly you have two sets of endpoints nested under different subdomains and their availability and / or content varies based on the subdomain? I am not sure how do you want to handle this without authentication (scopes), but if that is the case I would suggest to split such an API into two blueprints based on the subdomain.
Also sorry for the late reply – best if you post your questions regarding writing blueprints (and best practices) directly at Stack Overflow using the apiblueprint tag.
The API itself will handle the scoping, i just wasn't sure if there was a way of handling subdomains within the API Blueprint. A future feature perhaps? :P
You understand correctly. The API is going to determine which response to provide based on what resource that subdomain belongs to. The authentication will be handled the same regardless (probably a token in the header) but the scope will be determined by the subdomain.
Are there any plans in the long run to support subdomains? This could be quite handy for other uses cases as well I think. Perhaps other may agree?
No worries, should've gone to stackoverflow but thought I'd suggest it as a feature at the same time as asking for help :)
Are there any plans in the long run to support subdomains
Technically both HOST and FORMAT metadata are Apiary - specific. We plan to look at the HOST metadata and possibly split it into multiple components and / or move it completely in some sort of settings in Apiary (so the subdomain won't be specified in the blueprint at all).
The components can be used schemas, base URLs, CORS whitelists etc. The conceptual question is whether this is belongs to API Blueprint itself (as an API description format) or is it some sort of tooling specific metadata...
I guess it would depend on how common it is to make use of a subdomain that changes the response. If it were to be part of a tools metadata, then the user would be dependent on a tool that allowed them to use this. I can't see there being a large number of API's that would require this, but even in a simpler scenario than my own, you may wish to show a different API response to a single endpoint based purely on the subdomain. If for example each user is given a subdomain of their own, if user A tried to access resource A, it should return a response, but if they try accessing resource B it should fail:
GET usera.domain.com/resources/resource-a
200 OK
GET userb.domain.com/resources/resource-a
403 FORBIDDEN
Without this subdomain specification, it would not be possible to accurately document this. It would only be possible to specify the different responses that it might return, but it would not show that the error response is directly linked to the subdomain of that request. That said, I'm not sure how one would clearly show the link with the subdomain.
I'm currently working with an API that sits on multiple subdomains as well, and would be interested to see where this goes.
We need the ability to have a subdomain in the host which Apiary does not support.
Something like Http://{subdomain}.salesforce.com
Without this ability Apiary is of no use to us.
Very disappointing as i can pass in variable to set a folder off the end of the post but i cant pass in a variable for a subdomain into the host.
So close yet may as well be miles off target.
FYI anyone writing API's to work with Salesforce will also have this requirement.
was hoping this would work
FORMAT: 1A HOST: https:
POST [//{subdoimain}.secure.force.com/services/apexrest/]
Parameters subdoimain
But when i publish it i get https:////subdomain.secure.force.com/services/apexrest/
Also tried this
FORMAT: 1A HOST: https:/
POST [/{subdoimain}.secure.force.com/services/apexrest/]
Parameters subdoimain
But when i publish it i get https:///subdomain.secure.force.com/services/apexrest/
Also tried this but it is not a valid Post line
FORMAT: 1A HOST: https://
POST [{subdoimain}.secure.force.com/services/apexrest/]
Parameters subdoimain
I just want to be able to do this and have the parameter in the Host and not the Post.
FORMAT: 1A HOST: https://{subdoimain}.secure.force.com
POST [/services/apexrest/]
Parameters subdoimain
I vote for this feature too.
It will be great to have actions in blueprint doc that have different domains. We maintain two blueprint docs for two domains (one.domain.com and two.domain.com). But it can be merged. For us it would be prefered way.
Many API tools support multiple environments. I can use multiple variables as multiple hosts in the url and when i switch to different environment, the variables will change to different host. Is there any way to support the same feature？
from 5 years ago
I just want to be able to do this and have the parameter in the Host and not the Post.
FORMAT: 1A HOST: https://{subdoimain}.secure.force.com
POST [/services/apexrest/]
Parameters subdoimain
Any update?
