Skip to content

Commit

Permalink
docs: add preamble to low-level client section
Browse files Browse the repository at this point in the history
  • Loading branch information
booniepepper committed Dec 20, 2023
1 parent 60abea3 commit ca676b5
Showing 1 changed file with 27 additions and 17 deletions.
44 changes: 27 additions & 17 deletions docs/GENERATING-A-NEW-SDK.md
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,33 @@ TODO: Point to example build/publish CI workflows

## Low-level client

The following is a specification for a "low-level client" called something like `OpenFgaApi`.
This is the basic client that OpenAPI Generator will produce. It should already deal directly
with the serialization of requests, construction and dispatch of low-level HTTP requests, and
the deserialization of responses.

Each operation should follow common [Function signatures](#function-signatures).

In addition, the low-level client should support [Configuration](#configuration) and
[Per-request Override](#per-request-override).

### Function signatures

Functions of the low-level client should:

* Take as input a String `storeId`
* `CreateStore` and `ListStores` are the only operations that do not take/require a `storeId`
* The `storeId` should be validated as a non-null, non-blank String
* If applicable for the operation, take as input a modeled request `body`
* For example, `Check` should take a `CheckRequest` as its request `body`
* The `body` should at minimum be validated as non-null
* If it is a paginated operation, it should take as optional inputs an Integer `pageSize`
and a String `continuationToken`
* Take as an optional input a [`ConfigurationOverride`](#per-request-override)
* Produce as output a promise/future that will complete with:
* HTTP response details. This includes the status code, headers, and raw response body
* If applicable for the operation, a modeled request response

### Configuration

#### BaseConfiguration
Expand Down Expand Up @@ -342,23 +369,6 @@ ClientCredentials should be only static data, and will not be concerned with per
calls or retrieving an access token. ClientCredentials will be resolved as part of
[Authentication](#authentication).

### Function signatures

Functions of the low-level client should:

* Take as input a String `storeId`
* `CreateStore` and `ListStores` are the only operations that do not take/require a `storeId`
* The `storeId` should be validated as a non-null, non-blank String
* If applicable for the operation, take as input a modeled request `body`
* For example, `Check` should take a `CheckRequest` as its request `body`
* The `body` should at minimum be validated as non-null
* If it is a paginated operation, it should take as optional inputs an Integer `pageSize`
and a String `continuationToken`
* Take as an optional input a [`ConfigurationOverride`](#per-request-override)
* Produce as output a promise/future that will complete with:
* HTTP response details. This includes the status code, headers, and raw response body
* If applicable for the operation, a modeled request response

### Per-request override

The low-level client should allow an optional `ConfigurationOverride` as input for each of its
Expand Down

0 comments on commit ca676b5

Please sign in to comment.