Namespace to Gateway - (API) Support users creating services and routes without name conflicts

[rustyjux]

API Services Portal Issue

User Story

As a new API provider following the quick start tutorial, I need to be able to avoid/navigate service name conflicts to get up and running quickly and without issue.

Add an API call (in v3) which checks if a service name (and route?) is available. Once complete, this API call will require implementation within the CLI (logged in https://github.com/bcgov/gwa-cli/issues/101).

[ikethecoder]

On feature branch feature/ns-to-gw-v3-api there is a new endpoint: /routes/availability that takes a query parameter serviceName and returns the following JSON if it is available:

{
  "available": true,
  "name": "myservice",
  "host": "myservice.api.gov.bc.ca"
}

And in the case that it is not available, it will return one that is:

{
  "available": false,
  "name": "myservice-2",
  "host": "myservice-2.api.gov.bc.ca"
}

Could also consider showing multiple suggestions?

{
  "available": false,
  "suggestions": [
    {
      "name": "myservice-2",
      "host": "myservice-2.api.gov.bc.ca"
    },
    {
      "name": "gw-12345-myservice",
      "host": "gw-12345-myservice.api.gov.bc.ca"
    }
  ]
}

[rustyjux]

A few questions:

• one use case for this endpoint is definitely gwa generate-config, but will we also want to introduce it into apply/pg?
• Is the query parameter only for the service name and then the host is extrapolated from there? Don't we need to assess these separately?

In some cases name and host are the same (following the pattern you've shown in the examples), but even when using the templates in generate-config, the host is different (.dev being appended) and more broadly, users can do whatever they want with the route host, not tied to the service name.

Further, I would think users would be most concerned with the host, rather than the service name, since the name is strictly internal, while the route may/will be seen by outside parties.

[ikethecoder]

So what we are trying to convey is a structure like <servicename>.api.gov.bc.ca and for dev and test: <servicename>.dev.api.gov.bc.ca and <servicename>.test.api.gov.bc.ca

And the Service.Name and Route.Name can use <servicename> as well.

The “availability” API call will ensure that the Service.Name, Route.Name and Route.Hosts (all environment combinations) will also pass validation given the <servicename>.

Thinking the host is probably not useful being returned because you’ll have to manipulate it for the particular environment - so maybe just return the name?

I am thinking also that the suggested name if there is a conflict is <gatewayId>-<servicename>. For example, someone tries to use health.api.gov.bc.ca, I would rather it say gw-12443-health.api.gov.bc.ca than health-2.api.gov.bc.ca, so as not to portrait the legitimacy of the API endpoint. Thoughts?

[rustyjux]

I think the proposed structure (prod: <servicename>.api.gov.bc.ca, dev: <servicename>.dev.api.gov.bc.ca and test: <servicename>.test.api.gov.bc.ca) is sound and works well for generate-config use and modelling in our docs.

However, if I'm not mistaken, we don't enforce it, so there is nothing stopping users from having Service.Name: franks-bbq, Route.Name: franks-bbq-explosion and Route.Hosts: franks-hot-sauce.api.gov.bc.ca. So maybe someone comes in and checks availability on franks-hot-sauce - there is no use of this Service.Name, but does the check also look at the derived Route.Hosts? (I didn't dig in deep on the code in https://github.com/bcgov/api-services-portal/commit/455903ed9b8e492aeef08d9da23e248775908301)

Long story short, I think it would be good if part of the check logic was also to confirm availability of the corresponding Route.Name and Route.Hosts.

Maybe it isn't necessary to return the Route.Names or Route.Hostss which are also checked, but returning everything seems like a better approach for more transparency? Folks can choose to only use the ServiceName or availability values if that's all they want? Alternatively, only returning ServiceName and availability and disclosing the logic of what is checked in the API docs seems fine, since the other values are predictable.

Re: suggested alternate name, I agree. And if people don't like the suggestion and want to hunt for available routes, they can do so.

[ikethecoder]

Updates made https://github.com/bcgov/api-services-portal/commit/8eb965a08246976589e99e7f8a8654a75dd5a3df