Skip to main content

Document Microservice Metadata

Context​

There are different microservice-based projects within the company. Common functionality is designed as standalone microservices that shall be reused between these projects. A Service API Registry is being introduced.

Problem​

  • The service registry lacks information to make discovery efficient

Solution​

Document the microservices' metadata. The documentation can happen in human-readable form (like plaintext documents) or in machine-readable form (like XML, RDF documents). The latter enables the Service API Registry using the meta-data for service and API discovery.

L52 and L53 present two approaches on how a microservice meta-model could look like. We found the following point especially valuable to document in the microservices' metadata:
  • Name of the microservice
  • Purpose of the microservice
  • Responsible team or person
  • APIs (communication channels, API endpoints)
  • Managed entities
  • Dependent / enclosing microservices
  • Deployment information
  • Usage Costs

Maturity​

Proposed, requires evaluation.

Sources of Evidence​

L46:

  • Context: enterprise companies
  • several teams need to create/enhance common functionality like customer account
  • goal: effective reuse
  • solution: maintain enterprise-wide specifications about all microservices
    • document further metadata like status, ownership
  • make interfaces discoverable (other code)

L52:

  • Context: integrate with huge amount of dynamically growing architectural descriptions of very different microservices into consistent enterprise architecture
  • Solution: formalize small-decentralized mini-meta models (EA mini description)
    • based on Meta Object Facility (MOF) standard, 4 layers
    • M0: operational run-time or monitoring data
    • M1: meta-data of the microservice (purpose, API endpoints, usage costs) and the architectural models (e.g., components or comm. channels)
    • M2: global meta-model layer for collaborating microservices, integration rules for semi-automated integration
    • M3: defines language and semantic representations
    • => combine metamodels to larger entities, merge microservices into adjusting microservice architecture

L53:

  • Context: IoT system
  • integrating microservices requires descriptions of service APIs in syntactic and semantic level
  • description also good for searching existing services to compose new services by the machine
  • propose ontology for service description and discovery
  • ontology with 3 parts
      1. domain ontology: domain knowledge of entities and relations
      1. service profile: description of service interface of a domain:
      • category, process, parameter, result, condition of a method or event channel
      • SLAs
      • Should partially follow WSMO or OWL-S
      1. microservice structure in IoT system
      • virtual objects, methods, event channels, enclosing microservice
      • deployment related entities (where deployed to: device, cloud, fog, edge, remote cloud)
    • can be managed in ontology database associated with the API gateway
    • new service => add to database
    • other microservices query the ontology or run reasoning procedure through this ontology management service
  • besides, each service should provide a human-readable service manifest doc for developers
    • microservice name
    • service interfaces
    • as plaintext or XML/HTML or OWL/RDF
  • as this data might change: global service registry microservice to manage ontologies
    • possibly co-located with API gateway
    • manages ontology of microservices (meta-data)
    • service registration and discovery among multiple sites
    • microservice can talk to registry to publish its structures and interfaces
    • other microservices can make SPARQL query to locate it

L61:

  • Context: architectural description types
  • structural descriptions more linked to reuse than behavioral ones
  • still, behavioral viewpoint required to reason on functionalities of the system