Skip to content

Commit

Permalink
refactor: review comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@Magnus-Kuhn
Magnus-Kuhn committed Nov 15, 2024
1 parent dc9dd4c commit 879c106
Show file tree
Hide file tree
Showing 10 changed files with 40 additions and 38 deletions.
24 changes: 12 additions & 12 deletions _docs_integrate/data-model-overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,17 +51,17 @@ Tokens can be used to save arbitrary structured data on the Backbone, which is e

A Token has the following properties:

| Name | Type | Description | Remarks |
| ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| id | `string` | {% include descr_id class="Token" prefix="TOK" %} |
| createdBy | `string` | {% include descr_createdBy class="Token" %} | |
| createdByDevice | `string` | {% include descr_createdByDevice class="Token" %} | |
| content | `unknown` | The content of the Token. You can add whatever you want here. | will be encrypted before sent to the Backbone |
| createdAt | `string` | {% include descr_createdAt class="Token" %} | |
| expiresAt | `string` | {% include descr_expiresAt class="Token" %} | |
| forIdentity | `string` | Can be set to an enmeshed Address. If set, then only the Identity with that Address can retrieve the Token from the Backbone. |
| truncatedReference | `string` | {% include descr_truncatedReference class="Token" %} | saved only locally |
| isEphemeral | `boolean` | If set to `true` the Token will not be cached in the database and only displayed once. You will not be able to fetch this Token unless you remember its truncatedReference. |
| Name | Type | Description | Remarks |
| ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| id | `string` | {% include descr_id class="Token" prefix="TOK" %} |
| createdBy | `string` | {% include descr_createdBy class="Token" %} | |
| createdByDevice | `string` | {% include descr_createdByDevice class="Token" %} | |
| content | `unknown` | The content of the Token. You can add whatever you want here. | will be encrypted before sent to the Backbone |
| createdAt | `string` | {% include descr_createdAt class="Token" %} | |
| expiresAt | `string` | {% include descr_expiresAt class="Token" %} | |
| forIdentity | `string` | Can be set to an enmeshed address. If set, then only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can retrieve the Token from the Backbone. |
| truncatedReference | `string` | {% include descr_truncatedReference class="Token" %} | saved only locally |
| isEphemeral | `boolean` | If set to `true` the Token will not be cached in the database and only displayed once. You will not be able to fetch this Token unless you remember its truncatedReference. |

## RelationshipTemplate

Expand All @@ -80,7 +80,7 @@ A RelationshipTemplate serves two purposes:
| content | [`RelationshipTemplateContent`](#relationshiptemplatecontent) \| [`ArbitraryRelationshipTemplateContent`](#arbitraryrelationshiptemplatecontent) | The content of the RelationshipTemplate. If it is intended for a User of the enmeshed App, `RelationshipTemplateContent` has to be used. Otherwise, an `ArbitraryRelationshipTemplateContent` can also be used, which can be filled with anything and serves as a fallback if the `RelationshipTemplateContent` is not sufficient. | |
| expiresAt | `string` | {% include descr_expiresAt class="RelationshipTemplate" %} | will be encrypted before sent to the Backbone |
| maxNumberOfAllocations | `number` \| `undefined` | Can be set to limit the number of allocations of this RelationshipTemplate. A RelationshipTemplate is allocated by another Identity when it is first retrieved by it from the Backbone. After this value is reached, the Backbone rejects each request of any new Identity that wants to retrieve it. Identities that already allocated it will still be able to retrieve it. | |
| forIdentity | `string` | Can be set to an enmeshed Address. If set, then only the Identity with that Address can retrieve the RelationshipTemplate from the Backbone. | |
| forIdentity | `string` | Can be set to an enmeshed address. If set, then only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can retrieve the RelationshipTemplate from the Backbone. | |
| truncatedReference | `string` | {% include descr_truncatedReference class="RelationshipTemplate" %} | saved only locally |

## Relationship
Expand Down
22 changes: 12 additions & 10 deletions _docs_integrate/establish-relationships.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,26 +75,28 @@ How to send a Request via a RelationshipTemplate is explained in detail in the [

If the RelationshipTemplate is intended to establish a Relationship between the templator and another Connector, an [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) can be used instead of a RelationshipTemplateContent as the value of the [RelationshipTemplate's]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) `content`. An ArbitraryRelationshipTemplateContent has a single `value` property with no type restriction and is appropriate if the standard way is insufficient.

### Successfully Created RelationshipTemplate

If you have successfully created the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) on the templator, you will receive a success response from which you can read its `id`. As the templator is the creator of the RelationshipTemplate, the `createdBy` property contains the Address of the templator. For this reason, the value of the `isOwn` property is set to `true` in this context.

{% include copy-notice description="Save the `id` of the RelationshipTemplate so that you can refer to it and make it available to other Identities later. For the same reason, save the value of the property `truncatedReference`." %}

### Personalize the RelationshipTemplate

If the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is only for creating a Relationship with a single known Identity, you can set that Identity's Address in the RelationshipTemplate:
If the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is only for creating a Relationship with a single known [Identity]({% link _docs_integrate/data-model-overview.md %}#identity), you can set that Identity's `address` in the RelationshipTemplate:

```jsonc
{
...,
"content": {...},
"forIdentity": "<Address that the RelationshipTemplate is intended for>"
// ...
"content": {
// ...
},
"forIdentity": "<address that the RelationshipTemplate is intended for>"
}
```

Only that Identity will be able to continue with establishing a Relationship. This also protects sensitive data of that Identity contained in the RelationshipTemplate from outside access.

### Successfully Created RelationshipTemplate

If you have successfully created the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) on the templator, you will receive a success response from which you can read its `id`. As the templator is the creator of the RelationshipTemplate, the `createdBy` property contains the Address of the templator. For this reason, the value of the `isOwn` property is set to `true` in this context.

{% include copy-notice description="Save the `id` of the RelationshipTemplate so that you can refer to it and make it available to other Identities later. For the same reason, save the value of the property `truncatedReference`." %}

## Make the RelationshipTemplate Available

For an Identity to initiate a Relationship with the templator, it must use a valid [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) which is owned by the templator. Depending on whether the Identity is a Connector or an App user, a different approach must be used to make the RelationshipTemplate available to the Identity:
Expand Down
4 changes: 2 additions & 2 deletions _docs_use-cases/use-case-transport-create-own-relationshiptemplate.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ api_route_regex: ^POST /api/v2/RelationshipTemplates/Own$

{% include properties_list.html %}

Creates a RelationshipTemplate with the given parameters and submits it to the Backbone for other Identites to use.
Creates a RelationshipTemplate with the given parameters and submits it to the Backbone for other [Identities]({% link _docs_integrate/data-model-overview.md %}#identity) to use.

A [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) can be used by any party to either initiate a Relationship with the current Identity or retrieve a Request from an existing Relationship by a side-channel.

Expand All @@ -51,7 +51,7 @@ A [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relat
- `expiresAt` is the ISODateTime the RelationshipTemplate expires at. This should be set as small as possible and cannot be in the past.
- `content` describes the structure of the RelationshipTemplate. If an enmeshed App user shall receive this RelationshipTemplate, a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) is required as structure, otherwise an [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) containing any data can be used.
- `maxNumberOfAllocations` is the number of times the RelationshipTemplate can be accessed by different Identities to initiate a Relationship. The Backbone returns an error, if one accesses a RelationshipTemplate with no allocations left. Accessing the same RelationshipTemplate with the same Identity multiple times doesn't affect the number of allocations. The allocation counts, even if the Identity does not accept the RelationshipTemplate by discarding it.
- `forIdentity` can be set to an enmeshed Address. If set, only the Identity with that Address can access the RelationshipTemplate.
- `forIdentity` can be set to an enmeshed address. If set, only the Identity with that `address` can access the RelationshipTemplate.

## On Success

Expand Down
2 changes: 1 addition & 1 deletion _docs_use-cases/use-case-transport-create-own-token.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) that
- `content` an arbitrary JSON structure of the data to share via the Token.
- `expiresAt` is the ISODateTime the Token expires at.
- `ephemeral` indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for RelationshipTemplates and doesn't need to be stored.
- `forIdentity` can be set to an enmeshed Address. If set, only the Identity with that Address can load the Token from the Backbone.
- `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone.

## On Success

Expand Down
2 changes: 1 addition & 1 deletion _docs_use-cases/use-case-transport-create-token-for-file.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a
- `fileId` is the `id` of the File the Token should be created for.
- Optionally, `expiresAt` can be specified, which describes the ISODateTime the Token expires at.
- Optionally, `ephemeral` can be specified, which indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for [RelationshipTemplates]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) and don't need to be stored.
- Optionally, `forIdentity` can be specified, which names the Address of the only Identity that will be able to load the Token from the Backbone.
- Optionally, `forIdentity` can be specified, which names the `address` of the only [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that will be able to load the Token from the Backbone.

## On Success

Expand Down
6 changes: 3 additions & 3 deletions _docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,10 +48,10 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a

## Parameters

- `templateId` is the id of the RelationshipTemplate the Token should be created for.
- `templateId` is the `id` of the RelationshipTemplate the Token should be created for.
- `expiresAt` is the ISODateTime the Token expires at.
- `ephemeral` indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for RelationshipTemplates and doesn't need to be stored.
- `forIdentity` can be set to an enmeshed Address. If set, only the Identity with that Address can load the Token from the Backbone.
- `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone.

## On Success

Expand All @@ -60,4 +60,4 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a
## On Failure

- `templateId` does not resolve to a RelationshipTemplate.
- `expiresAt` lies in the past
- `expiresAt` lies in the past.
4 changes: 2 additions & 2 deletions _docs_use-cases/use-case-transport-create-token-qr-code-for-file.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,11 +48,11 @@ Creates a QR code for a [Token]({% link _docs_integrate/data-model-overview.md %

- `fileId` is the `id` of the File the Token and its QR code should be created for.
- Optionally, `expiresAt` can be specified, which describes the ISODateTime the Token expires at.
- Optionally, `forIdentity` can be specified, which names the Address of the only Identity that will be able to load the Token from the Backbone.
- Optionally, `forIdentity` can be specified, which names the `address` of the only [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that will be able to load the Token from the Backbone.

## On Success

- Returns the created QR code encoded as Base64.
- Returns the created QR code, whose content is Base64-encoded.

## On Failure

Expand Down
10 changes: 5 additions & 5 deletions ...e-cases/use-case-transport-create-token-qr-code-for-own-relationshiptemplate.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,19 +42,19 @@ api_route_regex: ^POST /api/v2/RelationshipTemplates/Own/{id}/Token$

{% include properties_list.html %}

Creates a QR code for a [Token]({% link _docs_integrate/data-model-overview.md %}#token) of a given [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate)
Creates a QR code for a [Token]({% link _docs_integrate/data-model-overview.md %}#token) of a given [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate).

## Parameters

- `templateId` is the id of the RelationshipTemplate the Token and its QR code should be created for.
- `templateId` is the `id` of the RelationshipTemplate the Token and its QR code should be created for.
- `expiresAt` is the ISODateTime the Token expires at.
- `forIdentity` can be set to an enmeshed Address. If set, only the Identity with that Address can load the Token from the Backbone.
- `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone.

## On Success

- Returns the created QR code encoded as Base64.
- Returns the created QR code, whose content is Base64-encoded.

## On Failure

- `templateId` does not resolve to a RelationshipTemplate.
- `expiresAt` lies in the past
- `expiresAt` lies in the past.
Loading

0 comments on commit 879c106

Please sign in to comment.