Multiple Internal base URIs


#1

Hi. Can you define multiple baseURIs in one RAML file? For example if internal testing is happening on multiple servers. If not, how might you do this?

Thanks
Michael


#2

You could set the domain as an uriParameter variable and then set an enum with all the possible domains for example.


#3

As @agines already said - what you could do is to have the following template URI

http://{env}.<your host address>.com/{version} whereas {env} is declared for each of your environment defined in the baseUriParameter node as an enum.


#4

Thanks @agines and Christian. Will try this out.


#5

I’m trying to do something else here with multiple baseURI variables and I’m hoping someone can help. This is an already existing API I am trying to document. It is a search function and the base URI is http://www.server.com/list/. It has URI parameters that may or may not be required; for example, look at http://www.server.com/list/Always_Required/sometimes_required2/sometimes_required3/sometimes_required4/. Always_Required can be a string (name of a city) and it will generate a list. It can also be an integer in which case sometimes_required2 is required (can’t have latitude without longitude). In a second case, the Always_required integer will require sometimes_required2 and might require sometimes_required3 and sometimes_required4 (the latter two lat/lon would help to form an area)

As I said this API is already in production and these values are not query parameters-they are URI parameters. Is there anyway to document this using RAML? Thanks.

michael


#6

First of all, assuming you can map your entire API to RAML and JSON/RAML types, I would implore you to try to get your team to switch over to using RAML going forward as the API first Single Source of Truth. I realize a lot of people exploring RAML for documentation purposes are coming from already existing APIs, but if you can move to the RAML API first design, you gain a number of advantages. It may be tricky to figure out tooling to keep your code in sync with the RAML, even without tooling to automate that (which there are a number of tools that can greatly increase efficiency and consistency), you could still design/talk to the RAML file(s) then implement however necessary.

Beyond that, your base URL is www.server.com/list (for this example). You then have an additional ALWAYS required path… I hope that means that it is always required… in which case I have to ask, what happens if you do NOT use the ALWAYS required path after the base url? Is it an API surface? Or returns 404?

So… you are also stuck in the conundrum that this is a poorly designed API. For example, requiring that sometimes required 2 is required IF the always required is a number is confusing, and frankly not a good design. Now, I realize you are coming in from the perspective that it is already designed/implemented/deployed, so you are trying to make the best of things by using RAML. I do not know… dont think there is a way in RAML to indicate that a given URL path (uriParameter) can be two different types… at best I think it would be ambiguous to something like a documentation parser without extra coding to handle different types.

As for using RAML to just document it, there is a way to do that, in that you would have something like:

/lists/{alwaysRequired}/{sometimes1}/{sometimes2}/{sometimes3}/{sometimes4}:
  uriParameters:
    alwaysRequired:
      -  type: string
         description: a string is a name
      -  type: integer
         description: an integer means longitude and then the /latitude is also required.
  sometimes1:
    type: integer
    description: if provided (not required), specifies the latitude.
  sometimes2:
    type: integer
    description: if provided (not required) specifies the longitude that defines an area (sometimes3 should be provided)
  sometimes3:
    type: integer
    description: if provided (not required) specifies the latitude that defines an area.

So the above works for me in Atom/API Workbench… but ONLY if I specify RAML 0.8. When I choose RAML 1.0, the array of type/descriptions for alwaysRequired doesnt seem to work. I see I still have a bit of reading/learning myself. :slightly_smiling:

Anyway, that should hopefully get you started. Try that out, see if that helps.


#7

Kevin, thank you so much for your response. I am definitely trying to get my team to start using RAML and the top down approach. It’s slow going as they’ve been doing this a lot longer than I but I forge ahead!

I agree with you that this is poorly formed. As we were reviewing my first draft (which was generated HTML from my RAML file) and he told me this was how it worked I knew it was not good design. And I just figured that out from what I’ve been reading the last two months! I will though try out your example and see what happens. Interesting that I just updated Atom/API workbench and was very excited that it accepted spec 1.0 but now I have to rollback to 0.8. :cry:

Again thanks for the info. I’ll let you know how it goes.

Edit: When I just use the base URI i get a 404.


#8

Woa… stay the course with 1.0!! :slight_smile: I am quite sure there is a better way to do it with 1.0. 1.0 adds a bunch of enhancements and I am sure there is another way to do it, I just havent mastered it yet. In fact soon I will hopefully be working with 1.0 a lot and get a better handle on your situation as well as others.


#9

What do you want to so here @Kevin_Duffey? That will definitely not work in 1.0 as it is invalid. :wink:


#10

Yah… I am definitely not quite up to date on what is and is not valid with the spec at this point. I think I took this from the 0.8 but cant remember now off hand. It will be great once the 1.0 is final that we can start in on more detailed tutorials including more advance use cases.


#11

Hello , I have now other question : What would happen if I use different endPoints and I would like to set them in the same .raml file ? For example these endPoints : www.uri1.es , www.uri2.es, www.uri3.es. Is there any solution ???


#12

How do each URI relate to the API? Are all those URIs implement the same API?


#13

Yes they are all implementing the same API. I would like to use RAML 0.8. I have two parts . For example:
1- www.url1/payments
2-www.url1/payrolls
I would like to set two .raml files : one in a payments folder and the other one in a payrolls folder . How would it be possible with raml 0.8? If that would be not possible, what would be the best solution ?
Thanks
Gorka


#14

I am not quite clear on the use of uri1, uri2, etc. Can you give a bit more detailed example? Is uri1 and uri2 different products, for example? But each would have payroll and payments? Is it that you want to build a service for payments and payroll but offer some sort of subdomain capability where by uri1 is company A while uri2 is company B, both using your services, but obviously different urls?