An extension depends on one or more modules

• All extensions depend on base.

• An extension may depend on one or more extensions.

• Starting from the extension that is farthest from base, the dependency relationship must be a "straight line from that extension and base".

  • Dependency cycles are not allowed
  • The following dependency relationships are allowed:
    • ext2 depends on ext1 depends on base
    • ext3 depends on base

    • ext4 depends on ext3 depends on base

      ext4 depends on ext2 depends on ext1 depends on base

    • base
  • The following dependency relationships are not allowed:
    • ext1 depends on ext1
    • ext2 depends on ext1 depends on ext2
    • ext2 depends on ext1 depends on ext3 depends on ext2
    • base depends on ext1

Services and Backends can be defined in base and in extensions

• A backend is an object defined in the catalog.json artifact of the module. A backend describes how to access a server, including the server URL, required headers, and authentication details.

• The path for the catalog.json artifact in base is <app>/services/catalog.json.

• The path for the catalog.json artifact in an extension is <extension>/services/self/catalog.json.

A service can be either dynamic or static

A dynamic service is contributed via the catalog.json artifact of a module.

• The entry on the catalog is not the "metadata" of the service but instead the way to fetch such metadata, hence the term "dynamic".
  • The metadata of a service is a document with the OpenAPI definition that describes the endpoints and the types of the service.
• In the catalog.json artifact, a service is defined as an entry of the services object:
  • The name of the service is used as the key.
  • The value is an OpenAPI definition with a single endpoint. The response yielded by fetching this endpoint should be the metadata for the dynamic service.
• Example of service entry in catalog.json:
  
  
  Description of the illustration dynamicservice.png
  
  

• A static service is contributed by providing the actual metadata for the service as an artifact of the application.

  • The default path for a static service in the base is <app>/services/<service name>/openapi3.json.
  • The default path for a static service in an extension is <extension>/services/self/<service name>/openapi3.json.
  • Example of static service:
    
    
    Description of the illustration staticservice.png
    
    

A service may or may not be registered

• Users can choose to register a service in an artifact, such as app-flow.json.

  • The name of the service is used as the registration entry key.
  • The registration value indicates how to locate the service and is typically the path to an artifact or the URI that identifies a dynamic service (for example, vb-catalog://services/extA:myservice ).

• It is no longer a requirement that all services are registered. See Endpoint ID below for a description of how the RT tries to resolve service names, regardless of whether it's registered or not.

• An advanced usage of the registration is to create new service names for existing services.

• Example:

  
  
  
  Description of the illustration serviceregistration.png
  
  

A service is expected to be uniquely identified by its name

• Not recommended: if a module uses the same "not registered" name for both a dynamic service and a static service, RT uses the dynamic service.

• A service name should be unique across different modules.

  • DT will warn the user if that's not the case.
  • Not recommended: RT handles the scenario in which the same service name appears in multiple modules, as explained later on in this document. However this may lead to "app level" programming errors that are hard to debug.

A module may be able to use services and backends from another module

• A service and a backend can be only used by a different module if that "object" is marked as accessible and if the module using the "object" depends on the module defining the "object".

  • An accessible service or backend defined in base can be used by any module.
    • Conversely, base cannot use services and backends defined by other modules.
  • An accessible service defined in extension extB can only be used by extB itself and by extensions that depend on extB (directly or indirectly).
    • The same applies to a backend

• Services that are not marked as accessible are private and can only be used by the module that defines them.

• Example of an accessible static service:

  
  
  
  Description of the illustration staticaccessible.png
  
  
• Example of an accessible dynamic service:
  
  
  Description of the illustration dynamicaccessible.png
  
  
• Example of an accessible backend:
  
  
  Description of the illustration backendaccessible.png
  
  

Endpoint Id

• An endpoint id is a string that identifies a service and an operation within that service.

  • For example, petstore/getAllPets refers to the operation from the service petstore, and which is identified by the id getAllPets.

• With the introduction of extensions, an endpoint id is expected to be "namespaced" to precisely indicate the module that contains the service.

  • Examples: base:petstore/getAllPets, extA:storage/createItem
    • The DT warns the user if the endpoint id is not fully qualified (if it does not have the extension id).
    • Adding a namespace to an endpoint id does not circumvent the visibility rules for services and backends (see Using services and backends from another module above).
      • In other words, using the endpoint id extB:myservice/getAll on a module that depends on the extension extB fails to resolve if extB is not exposing a service named myservice.

    Note:

    The RT can handle endpoint ids without namespaces, however, this is not recommended because it may lead to "app level" programming errors that are hard to debug.

• An endpoint id is typically used as an argument to a RestAction, and to a code making a REST request via the RT's REST Helper.

  • They are also used on ServiceDataProvider and related APIs.