Development Guidelines

Overview

The goal to develop and maintain services in Yaas is to develop them in a consistent and concise way following these API Development Guidelines. The YaaS team at SAP Hybris has figured out the best way to develop services, and shares this knowledge with you through these guidelines. In some cases, the guidelines are mandatory, while others are optional.

Also, follow the API Guidelines. For instance, always use the API response codes and error message payloads defined in that documentation.

API Versioning

Every exposed API must have a version, which is just a MAJOR number, such as v1. This ensures changes won't automatically break the product with every update, and users can decide when to upgrade to a newer version of the code. When the new version breaks API compatibility, you must increase the version number, such as v2.

The MAJOR API versions are used for all the Release Notes.

Events

Events must be named and documented consistently according to these guidelines. The message channels used to communicate specific events have topic owners, such as hybris.customer for the Customer service. Each topic owner can have multiple event types, described in the past tense, with a hyphen (-), such as password-updated. Therefore, name the specific event with a combination of the topic owner and the event type, such as hybris.customer.password-updated. The events created be each service are listed in the API Documentation by topic owner, such as Customer events. All of the YaaS events are published by the PubSub service so that other services can consume them.

Read the PubSub service and Events service documentation to learn how to publish, consume, and commit events.

Request Headers

Always forward hybris-request-id header and hybris-hop header to subsequent HTTP calls. The headers allow the monitoring toolset to correlate single HTTP requests. For more information, see the Hybris Headers document in the API Guidelines.

Multi-tenant services

Multi-tenant services are required to assure that the tenant of the request (hybris-tenant header) conforms to the resource-owning tenant. Also, the resource-owning tenant is expressed in the resource URL. For an example, refer to the Multi tenancy document in the Document service.

Secure a Service

Restrict access

Restrict access to resources by defining Scopes for different operations, and establish authorization rules. Follow the procedures in the Secure a Service documentation.

Last-mile security

Follow the Last-mile Security section to make sure that your internal service URL is not accessible by others.