Act like a REST client

[dennisvang]

The FDP spec mentions that the API must be REST compliant (which actually implies HATEOAS):

The API of the FDP follows the REST HATEOAS (Hypermedia as the Engine of Application State) guidelines by providing information so that the client is able to discover the available actions and access the resources it needs. [...]

Unfortunately the actual FDP reference implementation does not provide proper HATEOAS support, because it does not list allowable state transitions in every API response (like links on a web page). The specs do indicate that the RDF navigation information serves this purpose, but this is not the same thing, and it is at best incomplete.

However, the reference implementation does provide OpenAPI docs, at the /v3/api-docs path, which describe the API contract.
This information can still be used to make the client a bit more robust.

Currently, the client hard-codes the API paths, for example

https://github.com/FAIRDataTeam/FAIRDataPoint-client-redux/blob/91638ad338dc1b56ecaf889c18e8d99af05a3ee6/src/composables/fdpApi.ts#L45

One of the first things to do is get rid of all hard-coded URL path patterns, except for the root and/or /v3/api-docs paths.
Instead, we could start by getting the api-docs, extracting the available "operations" and mapping them to the corresponding paths.

So, instead of hard-coding the paths, we then hard-code the operationIds, and get the corresponding paths and parameters from the api-docs. This makes the client more robust w.r.t. future changes in the API contract, and it also prepares the ground for a future HATEOAS compliant API.

For example, from the api-docs below we can map the generateToken operation to the /tokens path, and could also extract information about parameters, request body, etc.:

{
  "openapi" : "3.1.0",
  ...,
  "paths" : {
    ...,
    "/tokens" : {
      "post" : {
        "tags" : [ "Authentication and Authorization" ],
        "operationId" : "generateToken",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/AuthDTO"
              }
            }
          },
          "required" : true
        },
        ...
      }
    },
    ...
  },
  ...
}

[mihailefter]

Hi @dennisvang!

This sounds nice. After checking the FDP specs again, I found out that there is already a mechanism possibly intended for this, i.e., dcat:endPointDescription on the FDP root record (Section 4.2.1), described as "The URL of the document describing the endpoint, its operations, services, parameters, etc. The description should be expressed in a machine-readable format, such as an OpenAPI or SmartAPI description."

It's not enforced (0..*), which is understandable. Still, I'd suggest we check for it, and expect that at some point the backend will provide it.

So, I would already implement the client this way:

• If we're not already at the FDP root, follow dct:isPartOf up until we reach it.
• Check the root record for dcat:endPointDescription. If present, use it to find the OpenAPI doc.
• If not present, check /v3/api-docs directly.
• If that's not available either, fall back to the current, manual way.

That way the client works today, and gets more robust automatically once the backend starts populating the property.

[mihailefter]

Hi @dennisvang!

I just checked the reference implementation's source and dcat:endpointDescription does not seem to be written anywhere. I found it only here and here. It looks like MetadataEnhancer.java never auto populates it for the root, unlike dcat:endpointURL, which is set right there.

Are there plans to have this populated automatically? Seems like a small addition given the pattern already exists right next to it.

And a minor side note: the spec text itself writes it as dcat:endPointDescription (capital P), see here, but the actual DCAT vocabulary term is dcat:endpointDescription (lowercase p), which is also what the reference implementation's SHACL shape and code consistently use. Might be worth fixing that typo in the spec too.

[dennisvang]

Are there plans to have this populated automatically? Seems like a small addition given the pattern already exists right next to it.

Thanks @mihailefter, I'll have a look at it.

And a minor side note: the spec text itself writes it as dcat:endPointDescription (capital P) [...]

Good catch! Apparently the same holds for dcat:endPointURL. I've fixed both in fdp-specs/fdp-specs.github.io#33, awaiting review by @luizbonino

[dennisvang]

Are there plans to have this populated automatically? Seems like a small addition given the pattern already exists right next to it.

Hi @mihailefter, FDP v1.22.0 now has dcat:endpointDescription statements for both /v3/api-docs and /swagger-ui.html.