Metadata Attachments

In addition to the industry-standard metadata formats like WSDL, XSD, Swagger and JSON Schemas, Sentinet allows attachment of a non-conventional metadata in the form of:

  1. Links

  2. Documentation files

  3. Keyword Tags

  4. Description Tags

These attachments can be added to services and APIs to provide additional documentation, references and tags to describe, document and categorize registered services. Attachments can also be added to Access Rules and Service Agreements.

Metadata attachments can be applied to physical and virtual services at different attachment levels. These attachment levels are:

  1. Service

  2. Service Version

  3. Operation

  4. Endpoint

Note

REST service versions may use Links, Keyword Tags and Description Tags in the Swagger documents generated for the service version.

To provide service-level attachments, select a service element in the Repository tree.

Service-level Attachments list
Figure. Service-level Attachments list.

For all other levels of service attachments, select the appropriate service element of the service version tree and click the ATTACHMENTS tab.

ATTACHMENTS table at the Service Version level
Figure. ATTACHMENTS table at the Service Version level.

Attachments can be added to the following Repository items:

  1. Service
  2. Service Version (at different levels)
  3. Access Rule
  4. Service Agreement
  5. Custom Entity

To add links and files, click the [+ Add] button in the Attachment table. In the Add Attachment dialog, provide a description for your attachment and select the Link or File radio button.

Add Attachment dialog box
Figure. Add Attachment dialog box.

  • Link

    Link can be any valid Uri that points to an internet or intranet resource. For example, a public URL to an API documentation, or a URL to a file in a Source Control System.

  • File

    Any file can be uploaded and stored in the Repository database, providing it is less than 10GB in size.

Once links or files are added as attachments, a user can click on them in the VALUE column to open links or download files.

Example: Links and Download Attachment File buttons
Figure. Example: Links and Download Attachment File buttons.

Keyword Tags

Keyword Tags serve the purpose of tagging services and service elements for additional categorization. They are also used in the generated Swagger/OpenAPI documents. To add a Keyword Tag, click the [+ Add] button.

Example: My API Keyword Tag
Figure. Example: My API Keyword Tag.

Description Tags

Description Tags create descriptive name-value pairs that are attached to the selected service tree element(s). For REST APIs specifically, these name-value pairs will appear in the generated Swagger/OpenAPI document (see Service Version Metadata chapter for REST APIs for more details on Swagger documentation). To add a Description Tag, click the [+ Add] button and type in a tag name and its description.

Description Tags example
Figure. Description Tags example.

Once attachments are saved, Description Tags will show as name-value pairs.

Saved Description Tags example
Figure. Saved Description Tags example.

There is one special Description Tag, Swagger::OperationSummary that offers smooth integration with REST API Swagger/OpenAPI. The value of this Description tag identifies Swagger/OpenAPI operation’s summary. When defined in Sentinet, it will be exported as Swagger operation’s summary. When imported from a Swagger document, it will be added as a Description Tag with the tag Swagger::OperationSummary and Description value as operation’s summary.

Searching Repository by Tags

Repository can be searched for any registered in it entity (see chapter Repository Search in this document for more details).

When searching by Keyword Tags specifically, you can place more than one tag in the Tags advanced search field separated by semicolon. For example: tag1;tag2. Each tag must match exact tag name (ignoring upper/lower case) and all searched tags must be attached to an entity if more than one tag is specified in the search criteria.

When searching by Description Tags specifically, you can place more than one description tag in the Tags advanced search field separated by semicolon. Each Description must be entered as tag=description pair. For example: MyDescriptionTag1=123; MyDescriptionTag2=567. Each description tag must match exact tag name and value (ignoring upper/lower case) and all searched tags must be attached to an entity if more than one tag is specified in the search criteria.