API template version

Hello,
I want to implement POST call /definition/template/adl2/{?version}.
As I understand, the template version inside the template file and URL can be different.
The URL version is optional. So what version should be used (saved in DB, used for query this exact template) if no version is provided in URL?

From docs I understand but I’m not sure:
if uploading new template: 0.0.1-alpha.1
if uploading template and previous version was 0.0.1-alpha.1 => 0.0.1-alpha.2
if uploading template and previous version was 0.0.1-rc.1 => 0.0.1-rc.2
if uploading template and previous version was 0.0.1 => 0.0.2-alpha.1
This is correct? Or depends on implementations and it’s not defined in docs?

Why template can have two versions? (Version defined in file and version defined in URL in POST). Or if a version can be only one then why can be version set in URL?

Thank you.

Hi,

The version is indeed optional, default version number and versioning mechanics is left open to implementation itself. In case of ADL2, the ARCHETYPE_HRID already have support for version id, but the {version} aspect of this endpoint is about internal versions assigned when published archetypes on the server. This functionality is however optional, as well is the client using {version} to control interaction with the server.

What is specified is that:

  • version value is following Semver
  • version is optional (defaulting to one version per template id)
  • uploading a template without specifying the version should return (in Location header) also the server assigned version (if versioning is present on that server)
  • requesting a version that does not exists in relation with template id should return an error (404)
  • using version pattern (e.g. 1.0 instead of 1.0.1) requesting template as well as no version parameter, should be supported by server (if that supports the internal versioning)
  • publishing a template id with a version that already exists, should return an error (409)
  • listing template should return also version information

Best regards,

Thank you.

So would be valid implementation for ADL2 POST call /definition/template/adl2/{?version}:

  • if URL has version - use that version?
  • if URL does not have version - use version from the ADL2 template file?
  • if the ADL2 template file does not have a version then this file is invalid?

All ADL2 templates should have an archetype_id attribute (mandatory) of type ARCHETYPE_HRID. This already contains version info, but it is ‘inside’ the archetype.
The {version} parameter on Rest API is different, it is an optional extra which a server could implement - although I’m not sure if any existing implementation has support for this option.

To respond to the point:

if URL has version - use that version?

yes, that’s right

if URL does not have version - use version from the ADL2 template file?

no, not necessary; the specs are not covering this part explicitly - I think it depends on the server that has or not versioning enabled (it might be and a version, or the version from archetype_id or no version at all) - so it depends on implementation; but in anycase (if present) it should be returned in the Location header.

if the ADL2 template file does not have a version then this file is invalid?

Correct, a template without (or with an invalid) archetype_id would be an invalid template.

1 Like