The Spree::Variant in OFN corresponds to a DFC SuppliedProduct. But
several Spree::Variant can be grouped under one Spree::Product which
wasn't exposed on the DFC API.
I'm adding a custom property here which can be used internally and
shouldn't break any other DFC tools.
A gotcha of this first test implementation:
The `ofn:` prefix has not been defined in the context. Software needs
to know that this is an Open Food Network attribute or ignore it.
We could define our own context and ontology and publish it on our
website but I don't see any benefit of that at this point.
We were aiming to use stable URLs to identify resources but the URL
helpers were still using dfc-v1.7 because that was the last and
overriding path of the mounted DFC Provider engine.
I observed new data from the DFC Prototype. It now uses the DFC 1.8
ontology with the hasQuantity object.
It now also uses PUT requests for updates because PATCH is not as well
supported. Rails doesn't care though.
I couldn't observe a request for the CatalogItem yet because the
Prototype failed to send it.
We wanted to use our own context before but now I found a better way for
the connector to cache the context and therfore we can use the original
implementation again.
The new DFC Connector is based on the new DFC context which changed all
URLs of all data types.
There's also a better way to access semantic properties now.
This protects us from the DFC website going down or the DFC updating
the context with breaking changes. We are in control of updating the
context now (opt-in to newer versions).
The DFC Prototype does include the context while the output of the DFC
Connector refers to the URL of the published context. While that's more
efficient, it's also brittle because the context is updated from time to
time. That happened three days ago and working with the newly published
context breaks our integration until we get an updated version of the
DFC Connector containing the new URLs for datatypes.
In other API specs, you provide example values in the schema. So the
specs contain examples which can be used for the documentation. But
instead of defining example data separately, we can use the generated
data by the specs. This way we document real output and don't have to
double up on documentation.
Note that we don't have schema definitions for the DFC API yet. And it
wouldn't make sense to replicate the DFC Ontology manually in JSON
Schema for this purpose. The DFC Connector ensures already that we
comply with the ontology. But I hope that we can use a tool at some
point to generate JSON Schema from the DFC Ontology which would add more
detail to the Swagger docs, I think.
I chose the simplest spec first to demonstrate how it works. The UI at
/api-docs now shows this endpoint with two possible responses.
The docs are missing an example response which I hope to add later.
We need to declare in each spec file for which endpoint the spec is
because it was just choosing the first declared one by default. The
first one was v1 and now it's dfc-v1.7.
Rswag doesn't look for specs in engines by default. We haven't added any
Rswag specs in the dfc_provider engine yet but that will come.
The generated API schema has some superfluous whitespace removed due to
a fix in the rswag gems.
These whitespaces were generated by
bundle exec rails rswag.
Might be related to a new version of rswag or
developers' trim trailing whitespace settings.
The customer endpoint now serves 2-letter ISO codes for countries and
accepts these for updates. It also serves and accepts region codes
(abbreviations) like VIC for Victoria.
Updates treat these fields as case-insensitive and either code or name
have to be present.
This commit also updates the Swagger documentation.
It's another read-only attribute.
Please note that JSON:API specifies a format of `date-time` which we
don't adhere to because it uses a `Z` in front of the timezone offset
which doesn't seem to be included in the default json serialisation.
So I didn't add the format and left it as simple `string`. Problem?
