Open APIs

Hello.

I have a few questions regarding TMF630 part 2.

In chapter 1. Polymorphic Collections and Types on page 5 after some examples the following is written:

All operations SHOULD be relative to the base types.
Other collections MAY be used at the discretion of the API Designer. In this case the operations exposed on the base collection may or may not be present on the derived collection.
Example:
• GET /resource/42?@type=Link
• GET/ logicalResource/42?@type=Link
• GET /link/42
An entity MUST declare in the Header the alternative URI that can be used to identify it. E.g / link/42 for
a logical resource of type link.
ID MUST always be relative to the base collection.

I don't understand the fragment about other collections and operations being relative to base types. 

I assume operations mean basically CRUD done by HTTP, that is GET, POST and so on.

Lets assume we have the following inheritance tree, like in the guidelines:

• logicalResource
  • TPE
  • Link

There exists a colleciton for logicalResource, on which I can perform operations. Howerver, what about collecitons for types derived from logicalResource? Is this example, there is only one base type, that is logicalResource. Does it mean that collections for derived types, TPE and Link are optional, and as is written, MAY be used at the discretion of API designer? If so, what does it mean that not all operations present on base type collection may be present on the derived colleciton? Does it mean that GET doesn't have to be implemented on collection for link? Or maybe I don't understand what operations are in this context? 

Also, I want to make sure that I understand one thing correctly - any changes to the model, like creating subclasses, adding states not present in the base API specification are meant to be included in the final API definition shipped by the implementing company? So there cannot be a situation, where there is a @type which is not included in the API definition?

Hi Piotr

Firstly, there is a JIRA relating to the extension pattern to clarify and improve the design guidelines part 2 on the polymorphic extension.  Also, now that the TMF API tooling and schema is evolving very fast, and in a very positive way (see github tmforum-rand), there may be scope to enhance the extension pattern further.  See [AP-4696] TMF630 - Extension Patterns - TM Forum JIRA

To answer your question about the collections on the derived types, I think Florin was trying to make the polymorphism design guidelines as permissive as possible and wasn't ruling out that some vendors' implementations may not support  all/any operations on the derived collections (some implementations may limit the operations on the derived collections, e.g. any TASK resources that have been implemented against the base collections/entities).

Regarding the schema extension definitions, yes, these should be provided by the ODA-C implementor/API provider.   Currently the @schemaLocation field should be used, containing a reference to the schema file and location of the schema definition within that file.  This probably needs to be clarified in the design guidelines part 2.

Good luck!