[FOLIO-602] Use consistent RAML baseUri parameter Created: 13/May/17  Updated: 21/Nov/22

Status: Open
Project: FOLIO
Components: None
Affects versions: None
Fix versions: None

Type: Task Priority: P3
Reporter: David Crossley Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: raml
Remaining Estimate: Not Specified
Time Spent: 10 minutes
Original estimate: Not Specified

Issue links:
Relates
relates to RMB-18 The "local apidocs" for "admin" and "... Closed
relates to RMB-280 Provide a POM snippet to configure lo... Closed
Sprint:
Development Team: Core: Platform

 Description   

Currently our RAMLs use many varied forms for the baseUri:

baseUri: http://localhost/
baseUri: http://localhost:8081/v1
baseUri: http://localhost:8081/{version}
baseUri: http://localhost:8081/user-import
baseUri: http://localhost:9130|http://localhost:9130/
baseUri: http://localhost:9130/user-import/
baseUri: http://api.example.com/{version}
baseUri: http://some-site.com/dummy-api
baseUri: http://github.com/org/folio/mod-user-import
baseUri: http://github.com/folio-org/mod-user-import
baseUri: https://github.com/folio-org/mod-user-import

All these examples have been taken from https://github.com/search?l=RAML&q=org%3Afolio-org+baseuri&type=Code and the module replaced with mod-user-import.

baseUri is used, at least, in the local apidocs applications. Each POM needs to transform it, so being consistent would ease things.

RAML spec

The RAML spec explains how baseUri is to be used:
https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/#base-uri-and-base-uri-parameters

The baseUri is intended to point to a site where one can try out the API. It can be a production or a test/sandbox host.

Host

api.example.com and some-site.com are wrong because they don't exist.

github.com is wrong because GitHub hosts the code repository, not a deployment.

localhost can be correct if a module or Okapi with modules runs locally.

An Okapi host of a FOLIO installation for public use may also be used.

Localhost port

localhost with port 80 ( http://localhost/ ) is wrong because no modules use 80 as default port.

localhost with port 9130 may work provided that the module is enabled in a locally running Okapi at Okapi's default port 9130.

localhost with port 8081 may work provided that the module runs at port 8081. Most modules use 8081 as their default port. Replace 8081 if a module uses a different default port.

A valid access token is needed if the 9130 Okapi port is used, while directly accessing the module at port 8081 doesn't require it.

Path

Currently there exists no module where the path starts with a version. Therefore http://localhost:8081/v1 and http://localhost:8081/{version} are wrong because they result in http://localhost:8081/v1/user-import or http://localhost:8081/1.0/user-import that don't exist.

The baseUri must not duplicate a path segment used lateron in the RAML file. Example showing wrong duplication:

baseUri: http://localhost:8081/user-import

/user-import:
  post:

This results in http://localhost:8081/user-import/user-import and doesn't work.


Generated at Thu Feb 08 23:07:00 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.