Open APIs

Hi,

in regards to planning of an implementation project (which may be e.g. TMF645), can you please share your insights and best practices in regards to the following questions?

a) the version information for an API implementation does not seem to be recommended as part of the URI, so did you choose to specify the version in the header?

b) the @type model seems to be proprietary on top of the OpenAPI specification, and which approach did you choose to specification which types are actually understood by the API? Eg. TMF645 talks about Place @types, so it could be an adress, geo coordinates, what3words, some internal id or whatever => how did you specify that for each of the API implementation versions, and did you enrich the TMF api with an additional proprietary endpoint to query about what is supported, or how did you approach that?

c) the APIs are generally pretty large and detailed, so in multiple iterations we don't plan to implement in a "big bang" approach, but to iteratively add more endpoints as needed, so did you find a good tool to specify which endpoints you decided for each implementation version, and which of the many parameters to support? we would like to avoid to having to modify the openAPI specification (like to remove endpoints or so) - is there any supportive system for that? then to follow a contract-first approach for implementation

Thanks a lot

Marco

------------------------------
Marco Nissen
Lyse Tele AS
------------------------------

Hi Marco

One small amendment - the recommended uri for API endpoints does include the major version (e.g. productCatalogManagement/v5/productspecification)

We mandate the semver versioning semantics for APIs, where a major version implies a backward compatibility breaking change, while a minor version preserves backward compatibility. So an implementation that wants to support multiple versions will typically expose two (or more) endpoints, one for each major version. However minor versions (and patches) are not represented in the endpoint, since consumers don't get to say which minor version they want. The consumer should not be affected by a minor version change (otherwise it's not a minor version change ...).

I will add that we expect consumers to be resilient - for example if a new output property was added in a minor version (which is generally not a breaking change) the consumer should be able to ignore the extra property that is received in the output.

Hi,

in regards to planning of an implementation project (which may be e.g. TMF645), can you please share your insights and best practices in regards to the following questions?

a) the version information for an API implementation does not seem to be recommended as part of the URI, so did you choose to specify the version in the header?

b) the @type model seems to be proprietary on top of the OpenAPI specification, and which approach did you choose to specification which types are actually understood by the API? Eg. TMF645 talks about Place @types, so it could be an adress, geo coordinates, what3words, some internal id or whatever => how did you specify that for each of the API implementation versions, and did you enrich the TMF api with an additional proprietary endpoint to query about what is supported, or how did you approach that?

c) the APIs are generally pretty large and detailed, so in multiple iterations we don't plan to implement in a "big bang" approach, but to iteratively add more endpoints as needed, so did you find a good tool to specify which endpoints you decided for each implementation version, and which of the many parameters to support? we would like to avoid to having to modify the openAPI specification (like to remove endpoints or so) - is there any supportive system for that? then to follow a contract-first approach for implementation

Thanks a lot

Marco

------------------------------
Marco Nissen
Lyse Tele AS
------------------------------