Developing a service - rettersoft/rbs-docs GitHub Wiki

What is a RBS Service?

RBS consists of many different services. Some services are developed and maintained by RBS it self and some by third party developers and published via RBS Service Store. A RBS service is a web service designed to handle requests and events coming from other services or users. By responding to requests and events it should be solving a specific business need like Order Handling, Order Shipping, Notification Sending etc. There can be many different types of RBS services.

Manifest File

Every RBS service declares a manifest file to list events and requests it receives and sends.

{
    "handler": "https://example.com/apiHandler",
    "eventHandler": "https://example.com/eventHandler",
    "id": "examplecompany.exampleservice",
    "name": "Example Service",
    "actions": {
        "receives": [
            "examplecompany.exampleservice.request.DO_SOMETHING_INTERESTING"
        ],
        "sends": [
            "rbs.notification.request.SEND_EMAIL"
        ]
    },
    "secretKey": "awesomesecretkey"
}

Handlers

There should be two handlers in your manifest.

• API Handler: will handle actions having an actionType request and get
• Event Handler: will handle actions having an actionType event

Actions

Actions are formatted like:

{COMPANY_ID}.{MODEL_NAME}.{ACTION_TYPE}.{ACTION_NAME}

• COMPANY_ID: A company which created this action. Any company or any developer can handle any action as long as it is installed by project owner. For instance if a company wants to receive rbs.order.event.ORDER_CREATED then they list this permission in their manifest file. If installed by project owner these events will be sent to service api handler.
• MODEL_NAME: A model name for which the action is related to. For instance it could be: order, shipment, payment etc.
• ACTION_TYPE: request | event | get
• ACTION_NAME: Name of action. SEND_EMAIL, ORDER_CREATED etc.

Examples:

• rbs.notification.request.SEND_EMAIL
• rbs.notification.event.EMAIL_SENT

Action Headers

Every action sent from RBS to a service has the following header values:

• X-Rbs-Action : Action identifier in 4 part format like: rbs.notification.request.SEND_EMAIL
• X-Rbs-ActionType : Event | Request
• X-Rbs-Identity: The identity type of whoever has sent this action.
• X-Rbs-ProjectId : The ID of the project this action belongs to.
• X-Rbs-ServiceId : If X-Rbs-Identity belongs to a service, this is the id of that service.
• X-Rbs-UserId : If X-Rbs-Identity belongs to a user role (will be described later) this is the id of that user.
• Authorization : JWT token which is signed by RBS with the secretKey in manifest file. Every service has a different secret stored in RBS.

Action Payload

Data sent for this action is sent in body of this request.