Available versions endpoint

[dfederschmidt]

This PR adds a new api/versions endpoint. It returns all schemas that are available on the schema server instance.

The response is in the following format:

{"versions":["1.0.0-rc.3","1.1.0-dev"]}

[rmouritzen-splunk]

@dfederschmidt : I notice this returns a fixed set of versions. Did you want me to add in the actual versions?

Also, what do you think of returning the API base URL along with the version? Also we should include the "default" version used when the version level isn't added before the API URL.

Something like:

{
  "default": {
    "version": "1.0.0",
    "url": "https://schema.ocsf.io/api"
  },
  "versions": [
    {
     "version": "1.0.0",
     "url": "https://schema.ocsf.io/1.0.0/api"
    },
    {
      "version": "1.1.0",
      "url": "https://schema.ocsf.io/1.1.0-dev/api"
    }
  ]
}

or:

{
  "default": {
    "version": "1.0.0",
    "url": "https://schema.ocsf.io/api"
  },
  "versions": {
    "1.0.0": "https://schema.ocsf.io/1.0.0/api",
    "1.1.0-dev": "https://schema.ocsf.io/1.1.0-dev/api"
  }  
}

[dfederschmidt]

@rmouritzen-splunk where is it returning a fixed set of versions? For the OpenAPI spec, there is a fixed set of example, yes.

The schemas that are actually available are fetched as part of the endpoint definition: https://github.com/ocsf/ocsf-server/pull/42/files#diff-7a02372413ad3b8ef8914da75e6ac6ac63c7600e05d6f01006e7815044b56cafR153

I'm not exactly sure whether it's easily possible to add in the URL because it would require the server to be aware what the external-facing domain is. Not sure whether that information is already available somewhere inside the server.

I also do not have any strong preference to the format, as long as I can get the list of available versions, I just went forward with the minimal response format possible.

[rmouritzen-splunk]

... where is it returning a fixed set of versions?

I see it now. I was confused by the OpenAPI spec logic.

... possible to add in the URL because ...

I suspect the web server knows its base URL. If not, we could use URLs starting with /api/... (without the scheme, domain, and port parts).

I also do not have any strong preference to the format, as long as I can get the list of available versions, I just went forward with the minimal response format possible.

Simple is always best at first. I'm suggesting adding URLs in the interest of being a bit more RESTful.

[dfederschmidt]

Added a new commit which adds URLs and the default version to the response payload.

{
  "default": {
    "version": "1.0.0-rc.3",
    "url": "/api"
  },
  "versions": [
    {
      "version": "1.0.0-rc.3",
      "url": "/1.0.0-rc.3/api"
    },
    {
      "version": "1.1.0-dev",
      "url": "/1.1.0-dev/api"
    }
  ]
}

I tried experimenting with returning absolute URLs and I'm in support of returning them, but I'm not exactly sure how to determine what protocol the client requests (http/https).

I was able to retrieve port, host configuration using

url = Application.get_env(:schema_server, SchemaWeb.Endpoint)[:url]

but I'm unsure how to construct the complete URL from that, given I'm not sure of the protocol. Maybe we can use the conn object to get the scheme from the request and then use that to construct the URL?

[dfederschmidt]

I added another commit that pulls schema and host from conn. This allows to return a full URL.

Is now what is returned

{
  "default": {
    "version": "1.0.0-rc.3",
    "url": "http://localhost:8080/api"
  },
  "versions": [
    {
      "version": "1.0.0-rc.3",
      "url": "http://localhost:8080/1.0.0-rc.3/api"
    },
    {
      "version": "1.1.0-dev",
      "url": "http://localhost:8080/1.1.0-dev/api"
    }
  ]
}

[rmouritzen-splunk]

A few changes... The swagger one looks like an oversight. The next one is to make the versions API work when running locally without the bits needed for the url configuration. The last one adds the version to the URL in the versions attribute even in the empty list.

Nice work!