Skip to main content

Service frontmatter API

Overview​

Services are just markdown files, with this comes the use of Content, MDX components and also front-matter.

Here is an example of the service frontmatter you will find in your /services folder.

/services/Orders/index.md (example)
---
# id of your service, used for slugs and references in EventCatalog.
id: Orders

# Display name of the Service, rendered in EventCatalog
name: Orders

# Version of the Service
version: 0.0.1

# Short summary of your Service
summary: |
  Service that contains order related information

# Optional owners, references teams or users
owners:
    - dboyne

# Optional messages this service receives and it's version
receives:
  - id: InventoryAdjusted
    version: 0.0.3

# Optional messages this service sends and it's version    
sends:
  - id: AddInventory  
    version: 0.0.3

# Optional details about the programming language and url for the code
repository:
  language: JavaScript
  url: https://github.com/event-catalog/pretend-shipping-service

# Optional badges, rendered to UI by EventCatalog
badges:
    - content: New service
      backgroundColor: blue
      textColor: blue
---

## Overview

This orders service gives API consumers the ability to produce orders in the systems. Events are raised from this system for downstream consumption.

<NodeGraph />

Required fields​

id​

  • Type: string

Unqiue id of the service. EventCatalog uses this for references and slugs.

Example
---
  id: Orders
---

name​

  • Type: string

Name of the service this is used to display the name on the UI.

Example
---
  name: My orders service
---

version​

  • Type: string

Version of the service.

Example
---
  version: 0.0.1
---

Optional fields​

summary​

Short summary of your service, shown on service summary pages.

Example
---
  summary: |
    service that contains everything about orders
---

owners​

An array of user ids that own the service.

Example
---
  owners:
    - dboyne
    - mSmith
---

sends​

An array of messages (ids) the service sends. These can be commands, queries or events ids.

Example
---
  sends:
    - OrderFulfilled
    - OrderComplete
---

receives​

An array of messages (ids) the service receives. These can be commands, queries or events ids.

Example
---
  receives:
    - OrderPlaced
    - OrderAdjusted
---

badges​

An array of badges that get rendered on the page.

Example
---
  badges:
    - content: My badge
      backgroundColor: blue
      textColor: blue
---

specifications​

Added in eventcatalog@2.6.0

Specifications to include on the page

Current supports AsyncAPI and OpenAPI files. When including the specifications the page will render badges and buttons for the specifications.

Example
---
  specifications:
    asyncapiPath: order-service-asyncapi.yaml
    openapiPath: openapi.yml
---

repository​

Added in eventcatalog@2.11.2

Repository language and code url for the service.

Example
---
  repository:
    language: JavaScript
    url: https://github.com/event-catalog/pretend-shipping-service
---