From 73ae19544b21e81bbe24ea835131e0fba305f9e0 Mon Sep 17 00:00:00 2001 From: Christian Blättler Date: Tue, 14 Nov 2023 15:54:06 +0100 Subject: implement feedback on merchant api specification --- core/api-merchant.rst | 97 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 66 insertions(+), 31 deletions(-) (limited to 'core/api-merchant.rst') diff --git a/core/api-merchant.rst b/core/api-merchant.rst index af757225..6e1b1f52 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -3697,8 +3697,8 @@ Creating token families **Response:** - :http:statuscode:`200 OK`: - The token family was created successfully. Returns a `TokenFamilyDetails`. + :http:statuscode:`204 No content`: + The token family was created successfully. :http:statuscode:`404 Not found`: The merchant backend is unaware of the instance. @@ -3707,6 +3707,10 @@ Creating token families interface TokenFamilyCreateRequest { + // Identifier for the token family consisting of unreserved characters + // according to RFC 3986. + slug: string; + // Human-readable name for the token family. name: string; @@ -3721,12 +3725,16 @@ Creating token families start_time?: Timestamp; // End time of the token family's validity period. - // If not specified, token family is valid indefinitely. - expiration_time?: Timestamp; + expiration_time: Timestamp; // Validity duration of an issued token. duration: RelativeTime; + // TODO: How should this be implemented? + // Indicates whether the token family can still issue tokens. Note: + // Already issued tokens will be valid, regardless of this setting. + // can_issue_tokens: boolean; + // Kind of the token family. kind: TokenFamilyKind; @@ -3743,14 +3751,13 @@ Creating token families Updating token families ----------------------- -.. http:patch:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_ID +.. http:patch:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG This is used to update a token family. **Request:** - The request must be a `TokenFamilyUpdateRequest`. Only fields that are not - undefined are updated. + The request must be a `TokenFamilyUpdateRequest`. **Response:** @@ -3765,23 +3772,27 @@ Updating token families interface TokenFamilyUpdateRequest { // Human-readable name for the token family. - name?: string; + name: string; // Human-readable description for the token family. - description?: string; + description: string; // Optional map from IETF BCP 47 language tags to localized descriptions. - description_i18n?: { [lang_tag: string]: string }; + description_i18n: { [lang_tag: string]: string }; - // Validity duration of an issued token. - duration?: RelativeTime; + // Start time of the token family's validity period. + start_time: Timestamp; - // Kind of the token family. - kind?: TokenFamilyKind; + // End time of the token family's validity period. + expiration_time: Timestamp; + + // Validity duration of an issued token. + duration: RelativeTime; + // TODO: How should this be implemented? // Indicates whether the token family can still issue tokens. Note: // Already issued tokens will be valid, regardless of this setting. - can_issue_tokens?: boolean; + // can_issue_tokens: boolean; } @@ -3805,19 +3816,57 @@ Inspecting token families .. ts:def:: TokenFamiliesList + // TODO: Add pagination + interface TokenFamiliesList { // All configured token families of this instance. - token_families: TokenFamilyDetails[]; + token_families: TokenFamilySummary[]; } + .. ts:def:: TokenFamilySummary + + interface TokenFamilySummary { + // Identifier for the token family consisting of unreserved characters + // according to RFC 3986. + slug: string; + + // Human-readable name for the token family. + name: string; + + // Start time of the token family's validity period. + start_time: Timestamp; + + // End time of the token family's validity period. + expiration: Timestamp; + } + + +.. http:get:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG + + This is used to get detailed information about a specific token family. + + **Response:** + + :http:statuscode:`200 OK`: + The merchant backend has successfully returned the detailed information + about a specific token family. Returns a `TokenFamilyDetails`. + + :http:statuscode:`404 Not found`: + The merchant backend is unaware of the token family or instance. + + The `TokenFamilyDetails` object describes a configured token family. .. ts:def:: TokenFamilyDetails interface TokenFamilyDetails { + // Identifier for the token family consisting of unreserved characters + // according to RFC 3986. + slug: string; + // Human-readable name for the token family. name: string; @@ -3848,25 +3897,11 @@ Inspecting token families } -.. http:get:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_ID - - This is used to get detailed information about a specific token family. - - **Response:** - - :http:statuscode:`200 OK`: - The merchant backend has successfully returned the detailed information - about a specific token family. Returns a `TokenFamilyDetails`. - - :http:statuscode:`404 Not found`: - The merchant backend is unaware of the token family or instance. - - Deleting token families ----------------------- -.. http:delete:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_ID +.. http:delete:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG This is used to delete a token family. Issued tokens of this family will not be spendable anymore. -- cgit v1.2.3