Where and What are the Specifications for Each Building Block for Dapr SDKs

[georgestevens-svs]

This was too long to paste into Discord, as we agreed to in our last meeting. Thus I put in here for your inspection. I hope this helps.

Where and What are the Specifications for Each Building Block for Dapr SDKs
6/14/22 by George Stevens (Solid Value Software) for the Dapr SDK Sig

Dapr SDK Contributors are asked to follow the Dapr building block “specifications” when developing SDK code and supporting materials. The specifications provide the following for the SDK code and documentation:

1. Naming conventions.
2. API conventions.
3. Required behavior specification, including errors and error handling.
4. Terms and concepts useful to use in the SDK code, documentation, and quick starts.

So, exactly where can one find the Dapr building block “specifications”? As you will see, this info is spread over a number of places. So it will be quite helpful to SDK Contributors and Maintainers to have a “map” of where to look for the “specification” info required. This document is the first step in providing such a map. By way of example, below is part of the hierarchy for the State Management Building block. It shows where in the hierarchy one can find the various forms of info listed above, but focused only on State Management. I assume the other Dapr Building Blocks are similar in the structure and naming of their documentation.

Building Blocks Concepts Page -- https://docs.dapr.io/concepts/building-blocks-concept/. This one page is the root for most of the relevant information for SDK code in all the building blocks. Question: Are there other important information sources OUTSIDE this root?

By clicking on the “State management” link in the above page, i.e. https://docs.dapr.io/developing-applications/building-blocks/state-management/state-management-overview/, you get to the “State management overview: Overview of the state management API building block” page.

Building Block Overview Page -- All building blocks have an overview page that contains a number of highly useful links. The Next Steps section of the Overview Page provides a broad range of additional detailed information. From the perspective of an SDK Contributor the key link in the State Management Overview page that are common to many of the other Overview Pages is the API Reference Page, outlined below.

API Reference page -- All Building Block Overview pages (should) have an API Reference Page (I have not yet determined if this is the case). For the State Management Building Block the link is https://docs.dapr.io/reference/api/state_api/
Note that this is also called the State Management API Reference in the State Management Overview page. The API Reference page provides detailed information as follows:

1. API behavior
2. Error behavior
3. How to invoke the API
4. The content and format of the Component Resource Definition files
5. And more.

To summarize, the above pages for each building block should be considered the “standard” places for SDK Contributors and Maintainers to consult when doing their work. That does not exclude consulting other pages referenced by the above “standard” pages. Note that for this to work across building blocks the Dapr documents must absolutely be structured (including standard URLs for navigation) in the above stated “standard” hierarchical manner. I believe this is mostly the case right now, but I have not checked completely.

Having a standard set of places to look for the information required by SDK Contributors and Maintainers will go a long way towards making it “really easy” for them to quickly get to the information they need to fulfill the requirements of the SDK Developers Guide. Indeed, having this makes almost everything regarding SDKs much easier and faster.