Charge your APIs Volume 2 - Guide your teams to achieve value-adding APIs

Guidelines are essential in every aspect of life, be it in our personal or professional lives. Guidelines are created by conscious decisions made by individuals or a group of people who understand the importance of consistency, structure, and organisation. They provide a set of standards that aim to guide and direct people towards a common goal.

Guidelines are created to ensure that everyone involved in a situation or process performs their roles and responsibilities effectively. They also help to minimise errors or mistakes, reduce conflicts, and increase efficiency. Whether it is a set of guidelines for a project, a code of conduct in the workplace, or rules and regulations set by the government, guidelines are designed to provide a clear direction on how to approach a particular situation.

Creating guidelines requires a conscious effort from those involved. It involves a careful evaluation of the situation or process, analysing potential outcomes, and making informed decisions. There are several factors to consider when creating guidelines. These include the purpose of the guidelines, the audience or stakeholders involved, and the potential impact of the guidelines.

The purpose of the guidelines is the most critical factor to consider when creating them. Guidelines must be clear, concise, and relevant to the situation or process they are intended to guide. They should be developed to address specific needs and must be based on factors such as available resources, constraints, and limitations.

The audience or stakeholders involved in the situation or process must also be taken into account when creating guidelines. Understanding the audience's needs and expectations will help guide the development of guidelines that are acceptable and effective. Involving stakeholders in the development process can also help to ensure that guidelines are relevant and practical.

Finally, the potential impact of the guidelines must be considered. Guidelines must be developed with the potential outcomes in mind. They should be designed to positively impact the situation or process being guided. The guidelines should also be evaluated regularly to ensure that they remain relevant and effective.

In conclusion, guidelines are essential tools that help to guide and direct people towards a common goal. They are created through conscious decisions made by individuals or a group of people who understand the importance of consistency, structure, and organisation. When creating guidelines, it is essential to consider the purpose, audience, and potential impact of the guidelines. By doing so, guidelines can be developed that are effective, relevant, and practical.

These decisions are the base level to foster guideline upon

In every organisation, there are certain decisions that form the base level to foster guidelines upon. These decisions are essential as they determine the overall direction, values, and culture of the organisation. They help in laying down the foundation for the long-term success of the company.

The first and foremost decision that needs to be made is the mission statement. This statement defines the purpose and reason for the existence of the organisation. It outlines the goals and objectives that the company wants to achieve and helps in aligning everyone's efforts towards a common goal. The mission statement should be concise, clear, and inspiring for the employees to work towards the company's vision.

The second decision that is crucial to the success of the organisation is the values. The values of the company reflect its culture and the behaviour that is expected from its employees. These values guide the employees in their work and help in building a sense of belonging towards the company. The values should be aligned with the mission statement and should reflect the company's personality.

The third decision that forms the base upon which guidelines are fostered is the organisational structure. The structure defines the hierarchy of the company, the roles and responsibilities of the employees, and the reporting lines. A well-defined structure helps in promoting accountability, clarity, and transparency in the organisation.

The fourth and final decision is the strategic plan. The strategic plan outlines the company's long-term goals and the actions required to achieve them. It helps in providing direction and focus to the organisation's efforts and ensures that everyone is working towards the same objectives.

In conclusion, these decisions form the base level to foster guidelines upon in any organisation. A strong mission statement, well-defined values, a clear organisational structure, and a strategic plan are all essential for the organisation's overall success. These decisions help in promoting a positive culture, aligning everyone's efforts, and maintaining accountability and transparency. By making these decisions with careful consideration and thoughtful planning, organisations can set the foundation for long-term success.

Guidelines should be challenged with the teams using them to evolve them over time

Guidelines are created to help teams work better and more effectively. When guidelines are created, they are often put in place with the idea that they will remain static and unchanged, but this is not always the best approach. Guidelines should be challenged with the teams using them to evolve them over time.

Challenging guidelines can help teams to identify areas where they may be able to improve their processes. It allows for open communication and collaboration, which can lead to creative solutions and ideas. Teams should not be afraid to speak up and challenge the guidelines that they are being asked to follow.

One important reason why guidelines should be challenged is that they may become outdated over time. As new technologies and ideas emerge, teams need to adapt and change their processes accordingly. By continuously challenging their guidelines, teams can ensure that they are evolving and staying ahead of the curve.

It is also important to remember that guidelines are not set in stone. They are created to provide structure and support, but they should not be seen as hard and fast rules. By challenging guidelines, teams can identify areas where they may need to be more flexible, or where the guidelines may be hindering their progress.

Finally, when guidelines are challenged, it can improve team engagement and morale. Teams are more likely to feel valued and empowered when they are able to speak up and offer suggestions. It can also lead to a sense of ownership and investment in the project, as team members feel like they are contributing to the success of the team.

In conclusion, guidelines should be viewed as a framework for success, not a set of rigid rules. Teams should be encouraged to challenge guidelines and to evolve them over time. This approach can lead to greater innovation, improved processes, and a more engaged and invested team. Ultimately, it can help teams to achieve their goals and to deliver more value to their clients and customers.

Adapt guidelines to actual situation within the teams

Teams are the cornerstone of every organisation. In today's fast-paced and ever-changing world, businesses need to be adaptable, flexible, and resilient to stay ahead of the curve. This is where adaptation of guidelines comes in. Guidelines are a set of rules or principles that enable teams to work collaboratively and efficiently. However, while guidelines are essential, it is equally important to adapt them to the actual situation within the teams.

When teams are created, different individuals come together, and it is important to understand that each team member has their own strengths, weaknesses, and working styles. While guidelines are meant to create a standardised process, it is important to understand that teams must be able to adapt to the unique needs of their members. For example, a team member who is more analytical may prefer a more structured approach, while another team member who is more creative may prefer a more flexible approach. Therefore, guidelines must be adaptable to ensure each team member can work in a way that best suits them.

To adapt guidelines to the actual situation within teams, it is important to assess the team's strengths and weaknesses. This can be done through regular feedback sessions, one-on-one meetings, and team-building exercises. When team members understand each other's strengths and weaknesses, they can work collaboratively and leverage each other's strengths to achieve their goals.

In addition, it is important to create an environment where team members can feel comfortable sharing their opinions and ideas. By doing this, the team can identify their strengths, weaknesses, and the areas where improvement is necessary. This collaborative approach helps to build trust, fosters creativity and innovation, and ultimately leads to better outcomes.

Another way to adapt guidelines to the actual situation within teams is by implementing a continuous improvement process. This involves regular review and reflection on the existing guidelines and identifying areas where improvements can be made. It is important to involve all team members in this process to ensure that everyone's ideas are heard, and concerns are addressed.

In conclusion, guidelines are essential for teams to work collaboratively and efficiently. However, it is equally important to adapt these guidelines to the actual situation within the teams. By assessing the team's strengths and weaknesses, creating an environment of trust and collaboration, and implementing a continuous improvement process, teams can optimize their performance and achieve their goals. Therefore, businesses must understand that guidelines must be adaptable to ensure each team member can work effectively and achieve the desired outcomes.

It was important to go into great detail about the connection between guidelines and decisions and to highlight different phases within possible processes. With regard to APIs, this means that we have to include the well-known abstraction layer API Interaction Patterns in order to take the first steps towards guidelines.

API Interaction Patterns

API Interaction Patterns refer to the different ways in which APIs (Application Programming Interfaces) can be designed and implemented. They are described by the following patterns.

• Tunnel: All requests are funnelled through a single endpoint, typically using the HTTP POST method. The endpoint then uses a combination of HTTP headers and message payloads to determine the specific operation to be performed. This style is often used for APIs that need to support legacy systems or have limited bandwidth.
• Resource: This models the system as a collection of resources, each with its own unique URI. Clients interact with the API by sending HTTP requests to the appropriate resource URI, using the appropriate HTTP method (e.g. GET, POST, PUT, DELETE) to perform the desired operation on the resource.
• Hypermedia: This pattern uses hypermedia links to enable clients to discover and navigate the API's resources. The API provides links to related resources, allowing clients to traverse the API without prior knowledge of its structure. The most common implementation of this style is the HATEOAS (Hypermedia as the Engine of Application State) constraint in RESTful APIs.
• Query API: It allows clients to retrieve data from the server using a query language. Clients submit queries to the API, which then returns the requested data in the requested format.
• Event-based API: This pattern allows clients to subscribe to events or messages that are published by the server. Clients receive notifications when the server publishes new events, allowing them to react in real-time to changes in the system. This style is often used for real-time applications, such as chat applications or stock trading platforms.

Must be mapped to the Guidelines

The use of the API Interaction Patterns now means that the guidelines have to be adapted or that corresponding guidelines have to be made accessible for each pattern. The last point also means that the organisation has to make a conscious decision on this.

In this respect, a decision tree and a final workflow are the first things to be created in order to put the decision into practice.

mkdocs documentation system acts as a store

Last week we took a look at mkdocs as a documentation system and set it up accordingly. When configuring mkdocs, we proceeded with the integration of external repositories using mkdocs-multirepo-plugin.

In detail, this means that we also create a new repo for the guidelines and integrate this into the documentation system via the plugin by adding two lines to the repos subsection of the multirepo plugin section.

1- multirepo:
2      cleanup: true
3      keep_docs_dir: true
4      repos:
5        - section: Decision Records
6          import_url: 'https://github.com/danielkocot/decision_records_example?branch=main&docs_dir=*'
7        - section: Guidelines
8          import_url: 'https://github.com/danielkocot/acme_api_guidelines?branch=main&docs_dir=*'

With this approach, all parts of the possible documentation in Markdown can be created independently and used in the same way. The coherent structure is then created using mkdocs.

Based on the existing ADR "Resource-oriented API", we now want to write a first guideline. As an example, we take the following elements of a first guideline. The elements are general information and meta-information.

1# General Guidelines
2
3## Follow API First Principle
4
5You `MUST` follow the API First Principle, more specifically:
6
7- You must define APIs first, before coding its implementation, using OpenAPI as specification language
8- You must design your APIs consistently with these guidelines
9- You must call for early review feedback from peers and client developers.
10
11## Provide API Specification using OpenAPI
12
13You `MUST` use the [OpenAPI specification](http://swagger.io/specification/) _(aka Swagger specification)_ as standard to define API specifications files. API designers have to provide the API specification files using YAML to improve readability.
14
15The API specification files should be subject to version control using a source code management system - best together with the implementing sources. Additionally, the API Specification `MUST` be validated and tested. For validation, [Spectral](https://github.com/stoplightio/spectral) could be used with a [custom ruleset based on these guidelines](/acme-api-ruleset.yaml).
16
17### Language
18
19The API description `MUST` be written in U.S. English. The language requirement covers both the elements of the API itself, such as resource and field names, as well as the human-readable parts of the OpenAPI file like summaries and descriptions for paths and schemas.
20
21If the content behind the API is available in different localized versions, the API `SHOULD` follow the following standards for localization:
22
23- The API should only return content in one language. It `SHOULD NOT` use different fields to provide multiple localizations (e.g., `description_de` and `description_en`).
24- Unless specified otherwise, the default language should be English. To allow API consumers to request another localization, the API should provide a `language` query parameter for all requests that may return localized content.
25
26## Provide API User Manual
27
28In addition to the API Specification, you `SHOULD` provide an API user manual to improve client developer experience, especially of engineers that are less experienced in using this API. A helpful API user manual typically describes the following API aspects:
29
30- API scope, purpose, and use cases
31- concrete examples of API usage
32- edge cases, error situation details, and repair hints
33- architecture context and major dependencies
34
35The user manual must be published online, e.g. via our API developer portal. Please do not forget to include a link to the API user manual into the API specification using the `#/externalDocs/url` property.

1# Meta Information
2
3## API Meta Information
4
5API specifications `MUST` contain the following OpenAPI meta information to allow for API management:
6
7- `#/info/title` as (unique) identifying name of the API
8- `#/info/version` to distinguish API specifications versions following semantic rules
9- `#/info/description` containing a proper description of the API
10- `#/info/contact/{name,email}` containing the responsible team
11
12## Semantic Versioning
13
14OpenAPI allows to specify the API specification version in `#/info/version`. To share a common semantic of version information API designers `MUST` comply to Semantic Versioning restricted to the format `<MAJOR>.<MINOR>.<PATCH>` for versions as follows:
15
16- Increment the **MAJOR** version when you make breaking API changes after having aligned this changes with consumers
17- Increment the **MINOR** version when you add new functionality in a backwards-compatible manner
18- Optionally increment the **PATCH** version when you make backwards-compatible bug fixes or editorial changes not affecting the functionality.
19
20Additional notes:
21
22- API designers `SHOULD` consider to use API version `0.y.z` for initial API design.
23
24Example:
25
26```yaml
27openapi: 3.0.3
28info:
29  title: Product Service API
30  description: API for <...>
31  version: 1.3.7
32  <...>

API Audience

Each API must be classified with respect to the intended target audience supposed to consume the API, to facilitate differentiated standards on APIs for discoverability, changeability, quality of design and documentation, as well as permission granting. We differentiate the following API audience groups with clear organisational and legal boundaries:

• company-internal: The API consumers with this audience are restricted to applications owned by the company.
• external-partner: The API consumers with this audience are restricted to applications of business partners of the company owning the API and the company itself.
• external-public: APIs with this audience can be accessed by anyone with Internet access.

The API audience is provided as API meta information in the x-company-audience field in the info-block of the OpenAPI specification.

Example:

1openapi: 3.0.3
2info:
3  title: Product Service API
4  description: API for <...>
5  version: 1.3.7
6  x-company-audience: company-internal
7  <...>

From Guidelines to rulesets

Now it is important to make these guidelines verifiable, as a purely textual presentation is not sufficient for this. And no one in an organisation wants to compare and reconcile all the API definitions with the guidelines.

For this purpose, rules and regulations are needed. These must now be created accordingly for the review. The sets of rules are basically dependent on the respective tool, the linter, which is used for the validation. The two best-known tools are Spectral from Stoplight and Redocly-cli.

In this post, we will take a look at vacuum, a new representative of the linter family. If you have Spectral already in use, you don't have to learn a new rule language with vacuum, but can directly use the already existing Spectral rulesets.

Let's start with the creation of a ruleset. The focus is on the Guideline points "API Meta Information" and "Semantic Versioning". For this we need a YAML file that will describe the ruleset. However, so that we do not have to start from scratch, we can use built-in rules or rulesets grouped by rules. In our case, the beginning of our ruleset will look like this, extends: [[spectral:oas, recommended]].

All rules are defined under the node rules. This results in the ruleset listed below for our previous guidelines.

1extends: [[spectral:oas, recommended]]
2rules:
3  include-contact-name:
4    description: Info contact section has to include a name of the responsible contact.
5    given: $.info.contact
6    severity: warn
7    then:
8      field: name
9      function: truthy
10  include-contact-email:
11    description: Info contact section has to include an email of the responsible contact.
12    given: $.info.contact
13    severity: warn
14    then:
15      field: email
16      function: truthy
17  include-title:
18    description: Info section has to include a title as identifying name of the API.
19    given: $.info
20    severity: error
21    then:
22      field: title
23      function: truthy
24  include-version:
25    description: Info section has to include a version following semantic rules.
26    given: $.info
27    severity: error
28    then:
29      field: version
30      function: truthy
31  valid-semantic-version:
32    description: Versions are restricted to the format <MAJOR>.<MINOR>.<PATCH>, e.g. 1.0.0.
33    given: $.info
34    severity: error
35    then:
36      field: version
37      function: pattern
38      functionOptions:
39          match: ^([0-9]+)\.([0-9]+)\.([0-9]+)$

Now we can test the rule set for the first time. For this purpose, the following description of an API was created.

1openapi: 3.0.2
2info: 
3  title: Testing API
4  description: API for testing purposes
5  version: 1.0.0
6  contact: 
7    name: Daniel Kocot
8    email: daniel.kocot@codecentric.de
9servers: 
10  - url: http://api.codecentric.de/test-api
11tags: 
12  - name: test 
13paths:
14  /test:
15    get:
16      description: API endpoint for testing purposes
17      tags: 
18        -  test
19      operationId: test 
20      responses: 
21        '200':
22          description: OK

With vacuum lint -d -r acme-api-ruleset.yaml test-api.yaml, we receive the following feedback.

1██    ██  █████   ██████ ██    ██ ██    ██ ███    ███
2██    ██ ██   ██ ██      ██    ██ ██    ██ ████  ████
3██    ██ ███████ ██      ██    ██ ██    ██ ██ ████ ██
4 ██  ██  ██   ██ ██      ██    ██ ██    ██ ██  ██  ██
5  ████   ██   ██  ██████  ██████   ██████  ██      ██
6
7version: 0.1.1 | compiled: 2023-05-04T14:32:00Z
8🔗 https://quobix.com/vacuum | https://github.com/daveshanley/vacuum
9
10
11 INFO  Linting against 47 rules: https://quobix.com/vacuum/rulesets/recommended
12
13
14
15          Linting passed, A perfect score! well done!

Conclusion

Thus, with little effort, based on a decision, we have created both a first iteration of guidelines and a first ruleset based on them. Next week, we'll continue at exactly this point and move onto the path of testing around APIs. We will start with the ruleset. So stay tuned.

References

GitHub - danielkocot/decision_records_example

GitHub - danielkocot/acme-api-initiative: An example for a documentation platform with mkdocs

GitHub - danielkocot/acme-api-guidelines