Open APIs

Hello,

How are the URLs for OpenAPIs supposed to be structured?

Taking Appointing as an example (the same question applies across the board): the API conformance tests for Appointing say "Requests must be addressed to the endpoint provided for certification, specifically they must be addressed to the URI defined by the concatenation of the {apiRoot} and the specific resource, where the {apiRoot} is defined as {serverRoot}/appointmentManagement/v4, being {serverRoot} defines the certification endpoint."

I am unclear what "being {serverRoot} defines the certification endpoint" means. Is the {serverRoot} just scheme, host and port? or can it include some top-level path element?

The spec says the {apiRoot} is /appointmentManagement/v4/ but does this need to be the start of the URL path? or can it be subordinate to some other starting path elements?

I.e. do implementors need to expose URLs like this:
https://HOST:PORT/appointmentManagement/v4/appointment/appointment
https://HOST:PORT/appointmentManagement/v4/appointment/appointment/{id}
https://HOST:PORT/appointmentManagement/v4/appointment/searchTimeSlot
https://HOST:PORT/appointmentManagement/v4/appointment/searchTimeSlot/{id}
I.e. the path must begin with the {apiRoot}, /appointmentManagement/, in this case.

Or are implmentors free to prepend their own elements to the path?
https://HOST:PORT/my/additional/path/appointmentManagement/v4/appointment/appointment
https://HOST:PORT/my/additional/path/appointmentManagement/v4/appointment/appointment/{id}
https://HOST:PORT/my/additional/path/appointmentManagement/v4/appointment/searchTimeSlot
https://HOST:PORT/my/additional/path/appointmentManagement/v4/appointment/searchTimeSlot/{id}
(I.e. we can have arbitrary path elements before the {apiRoot} part).

In addition, the Swagger from GitHub says this:
https://HOST:PORT/tmf-api/appointment/v4/appointment
https://HOST:PORT/tmf-api/appointment/v4/appointment/{id}
https://HOST:PORT/tmf-api/appointment/v4/searchTimeSlot
https://HOST:PORT/tmf-api/appointment/v4/searchTimeSlot/{id}
Which I read as meaning the path must begin /tmf-api

Which of these approaches is the intended one?

For info, here is an extract from the swagger file on Github.
TMF646-Appointment-v4.0.0.swagger.json
"host": "serverRoot",
"basePath": "/tmf-api/appointment/v4/",
"schemes": ["https"],
"paths": {"/appointment": {}
"/appointment/{id}": {}
"/searchTimeSlot": {}
"/searchTimeSlot/{id}": {}}



------------------------------
Alasdair MacLeod
BT Group plc
------------------------------