diff --git a/asynchronous-api-guidelines/02_asynchronous_api_guidelines/main.md b/asynchronous-api-guidelines/02_asynchronous_api_guidelines/main.md index 71d92b5..e647ad6 100644 --- a/asynchronous-api-guidelines/02_asynchronous_api_guidelines/main.md +++ b/asynchronous-api-guidelines/02_asynchronous_api_guidelines/main.md @@ -10,7 +10,7 @@ That contract **MUST** contain enough information to use the API (servers, URIs, ### API First -Asyncrhonous APIs **SHOULD** use the API First principle : +Asynchronous APIs **SHOULD** use the API First principle : - The API designs **SHOULD** involve all relevant stakeholders (developers, consumers, ...) to ensure that final design fulfil requirements from different perspectives - The resulting API specification will be the source of truth rather than the API implementation diff --git a/asynchronous-api-guidelines/03_asyncapi_kafka_specs/b_guidelines.md b/asynchronous-api-guidelines/03_asyncapi_kafka_specs/b_guidelines.md index 4da1555..1ad6c14 100644 --- a/asynchronous-api-guidelines/03_asyncapi_kafka_specs/b_guidelines.md +++ b/asynchronous-api-guidelines/03_asyncapi_kafka_specs/b_guidelines.md @@ -26,13 +26,13 @@ This access control is handled through Role-Based Access Control (RBAC) implemen ### Spec granularity -In FDP all resources are grouped by namespace. +In Fast Data Platform (FDP) all resources are grouped by namespace. For that reason specs **SHOULD** be created with a relation 1:1 with namespaces. In other words, every namespace will have an AsyncAPI spec including all the assets belonging to that namespace. Different granularities **MAY** be chosen depending on the needs.  -### Meaningful descriptions +### Meaningful descriptions All fields included in the specs **MUST** include a proper description.  @@ -129,7 +129,7 @@ channels: description: A description of the purpose of the topic and the contained information servers: ["pivotalDev", "pivotalSit", "pivotalPro"] x-metadata: - myField1: myValue1 + myField1: myValue1 myField2: myValue2 x-configurations: pivotal.dev: