Where is it appropriate to use URI vs URL?


In RAML 0.8 (today), there’s a baseUri property that identifies the service endpoint (where the API is served), and a uriParameters property that describes aspects of the parameters that appear in the relative URIs of the resources (e.g. in /users/{userId} it can be used to describe the userId part).

But really, baseUri should be baseUrl: it’s a specific location of a service. Identifying it as a URL rather than a URI indicates its true purpose: the location of the service, not just an abstract identifier. Similarly, baseUriParameters should be baseUrlParameters.

How about uriParameters then – are they identifiers of resources, or locations of the resources?


I’m a bit confused - so if I say “baseURL” in the RAML spec, will it still be accurate?


Sorry for the confusion. You still need to use baseUri in RAML 0.8, but I’m thinking we should change that to baseUrl in RAML 0.9.


ahhhh, okay. thanks!


URI is often used to signify either a URL or a URN. It is still accurate to call it baseUri when talking about the location of the API. Having said that, given that RAML is HTTP-centric, enabling the use of URNs can be misleading and more often than not it will not work.

Given that we are at 0.x it is a +1 from me.


My sentiment exactly.

Given RAML’s HTTP specific semantics, allowing non URL’s anywhere will be ambiguous.


Sorry, guys but I feel obliged to go all academic on you before we move to practicalities…
We all agree that every URL is a URI and we also agree that not every URI is a URL. Now, in the world of REST the only thing of interest is a URL because without it you can’t get a representation. Ok, so everything is a URL, right? Well, in the context of a REST modelling language, not really, because it cannot define every possible URL valid in your API. Rather, it relies on templates to do that. The literal string:


is not a valid URL but it is a valid URI Template
So, given the fact that we are defining a formal language, I propose we change baseUri to baseUrlTemplate (url not uri) and so we remove ambiguity and keep it relevant to REST. In the same spirit of focus on urls we can rename the uriParameter to urlParameter.


+1 on using baseUrl.

On a separate, but related, note I would like to this property only valid when documenting an existing API and invalid when designing an API (e.g. in the API designer).

One of the challenges with using the same definition/spec for designing and documenting api’s is that there may be certain attributes that are implementation specific, this is the case with baseUri.

Also regardless of if there is a change made to the spec or not, demo’s of API Designer should never include the definition of this attribute IMO.


Another thought:

If the api.raml file actually lives at the baseUrl (see separate thread on this) then why does the baseUrl need defining in the raml file even? In a previous incarnation of APIKit I was involved in, when we used swagger for documenting the API, we never returned baseUri ever, it wasn’t needed.


Something needs to tell various tools that consume the spec of an API where they can find the service endpoint. It can be outside the spec itself, and certainly there are some good reasons to do that, but if it’s inside the spec, then the information is in a single place. It does couple implementation to the interface in the sense of the location of the implementation, though that could be a virtualized URL.

Note that, in API Designer, the imminent mocking service will surface a baseUrl where you can hit the mock of the API.


Well my vote is that we don’t couple interface and implementation location. I’m actually kinda surprised this is being discussed…

  • Design-time: One of the advantages of RAML over other specifications is that it supports a design-first approach, through i) human readability ii) patterns/traits iii) ability to view/try api without building/hosting an implementation. For me, and others I have spoken to, defining a baseUrl here directly conflicts with this design-first philosophy and it’s worrying to see it in the example on the raml.org homepage.
  • Runtime I could just about deal with a runtime request for an, already implemented/deployed, api returning a baseUrl within a RAML file it returns, but at the same time i) I don’t see why it’s needed, it’s the same url you just used when request the RAML doc. ii) it means an optional baseUrl attribute is required in the spec, which then causes confusion at design-time.

Two other points:

  1. By defining the the baseUrl in design-time, not only are you making decisions about where the API will be hosted (which potentially isn’t your decision to make) but you are also taking security decisions about if the API should be exposed via http or https!
  2. If you generate a client based on a baseUri you are also most probably binding your client to a an implementation too.

In summary IMO baseUrl needs to be gone by version 1.0.


I agree that baseUrl is not necessary in RAML. When I create the definition of a service, the last think I want to specify is where is this service is going to be deployed. It’s completely irrelevant at API design time.


I have to agree with dfeist. We’re used to see the pair one api <-> one provider, like facebook <-> facebook api. But a detached location and specification could lead to scenarios much more powerful.

What if tomorrow is defined a social wall api to have a decentralised facebook? Should be there one RAML file per each installation of the decentralised facebook app?

Or in a more realistic scenario: Wordpress has a REST api. I have wordpress like thousands of others. With the url in RAML I would have to have a different RAML and a different client for each installation of wordpress I want to interact with.

Of course to have an interactive console the url is required. But it is perfectly acceptable that this url is configured in the console itself.


URL is the common type of URI. URIs are strings of characters use to establish a resource over a network. You can Simply say the URI is the Identifiers or Locators. While the URN is the URI too.
Confused? Don’t worry. :slight_smile: Have a Cup of Coffee :coffee: and Continue

So, here is URI vs URL

URL is Uniform Resource Locator

URI is Uniform Resource Identifier

URN is Uniform Resource Name

Basically, the URN and URL are the subsets of URI. Both URN and URL are the Types of URI. But, we can classify the URIs are Locators that are URLs, as names that URNs.

URN is Uniform Resource Name and its Function is Exactly Like the person’s name. While URL is Uniform Resource Locator and it resembles ethe Person’s Street Address.

Simply, URN defines the identity of an item and URL helps to find it. Hence URL is URI. But all the URIs are not URLs.

The thing which makes URI an URL is the inclusion of network location or access mechanism. e.g FTP://, HTTP:// or HTTPS://

While the URN is the Globally Unique. URN is the unique name for identification.

Source: https://www.dailytutorialz.com/url-meaning/