implement feedback on merchant api specification

1 files changed, 66 insertions, 31 deletions

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.