docs(mnq): revamp (#585)

Author: scaleway-bot

packages/clients/src/api/mnq/v1alpha1/api.gen.ts

@@ -41,7 +41,8 @@ const jsonContentHeaders = {
 /**
  * MnQ API (beta).
  *
- * This API allows you to manage Messaging or Queueing brokers. MnQ API (beta).
+ * This API allows you to manage Scaleway Messaging and Queueing brokers. MnQ
+ * API (beta).
  */
 export class API extends ParentAPI {
   /** Lists the available regions of the API. */
@@ -72,7 +73,10 @@ export class API extends ParentAPI {
     )
 
   /**
-   * List namespaces.
+   * List namespaces. List all Messaging and Queuing namespaces in the specified
+   * region, for a Scaleway Organization or Project. By default, the namespaces
+   * returned in the list are ordered by creation date in ascending order,
+   * though this can be modified via the `order_by` field.
    *
    * @param request - The request {@link ListNamespacesRequest}
    * @returns A Promise of ListNamespacesResponse
@@ -81,7 +85,8 @@ export class API extends ParentAPI {
     enrichForPagination('namespaces', this.pageOfListNamespaces, request)
 
   /**
-   * Create a namespace.
+   * Create a namespace. Create a Messaging and Queuing namespace, set to the
+   * desired protocol.
    *
    * @param request - The request {@link CreateNamespaceRequest}
    * @returns A Promise of Namespace
@@ -103,7 +108,8 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Update the name of a namespace.
+   * Update the name of a namespace. Update the name of a Messaging and Queuing
+   * namespace, specified by its namespace ID.
    *
    * @param request - The request {@link UpdateNamespaceRequest}
    * @returns A Promise of Namespace
@@ -125,7 +131,9 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Get a namespace.
+   * Get a namespace. Retrieve information about an existing Messaging and
+   * Queuing namespace, identified by its namespace ID. Its full details,
+   * including name, endpoint and protocol, are returned in the response.
    *
    * @param request - The request {@link GetNamespaceRequest}
    * @returns A Promise of Namespace
@@ -143,7 +151,10 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Delete a namespace.
+   * Delete a namespace. Delete a Messaging and Queuing namespace, specified by
+   * its namespace ID. Note that deleting a namespace is irreversible, and any
+   * URLs, credentials and queued messages belonging to this namespace will also
+   * be deleted.
    *
    * @param request - The request {@link DeleteNamespaceRequest}
    */
@@ -157,8 +168,11 @@ export class API extends ParentAPI {
     })
 
   /**
-   * Create a set of credentials. Create a set of credentials for a specific
-   * namespace.
+   * Create credentials. Create a set of credentials for a Messaging and Queuing
+   * namespace, specified by its namespace ID. If creating credentials for a
+   * NATS namespace, the `permissions` object must not be included in the
+   * request. If creating credentials for an SQS/SNS namespace, the
+   * `permissions` object is required, with all three of its child attributes.
    *
    * @param request - The request {@link CreateCredentialRequest}
    * @returns A Promise of Credential
@@ -180,7 +194,9 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Delete credentials.
+   * Delete credentials. Delete a set of credentials, specified by their
+   * credential ID. Deleting credentials is irreversible and cannot be undone.
+   * The credentials can no longer be used to access the namespace.
    *
    * @param request - The request {@link DeleteCredentialRequest}
    */
@@ -220,7 +236,9 @@ export class API extends ParentAPI {
     )
 
   /**
-   * List credentials.
+   * List credentials. List existing credentials in the specified region. The
+   * response contains only the metadata for the credentials, not the
+   * credentials themselves (for this, use **Get Credentials**).
    *
    * @param request - The request {@link ListCredentialsRequest}
    * @returns A Promise of ListCredentialsResponse
@@ -229,7 +247,10 @@ export class API extends ParentAPI {
     enrichForPagination('credentials', this.pageOfListCredentials, request)
 
   /**
-   * Update a set of credentials.
+   * Update credentials. Update a set of credentials. You can update the
+   * credentials' name, or (in the case of SQS/SNS credentials only) their
+   * permissions. To update the name of NATS credentials, do not include the
+   * `permissions` object in your request.
    *
    * @param request - The request {@link UpdateCredentialRequest}
    * @returns A Promise of Credential
@@ -254,7 +275,9 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Get a set of credentials.
+   * Get credentials. Retrieve an existing set of credentials, identified by the
+   * `credential_id`. The credentials themselves, as well as their metadata
+   * (protocol, namespace ID etc), are returned in the response.
    *
    * @param request - The request {@link GetCredentialRequest}
    * @returns A Promise of Credential

packages/clients/src/api/mnq/v1alpha1/types.gen.ts

@@ -24,23 +24,25 @@ export type NamespaceProtocol = 'unknown' | 'nats' | 'sqs_sns'
 
 /** Credential. */
 export interface Credential {
-  /** Credential ID. */
+  /** ID of the credentials. */
   id: string
-  /** Credential name. */
+  /** Name of the credentials. */
   name: string
-  /** Namespace containing the Credential. */
+  /** Namespace containing the credentials. */
   namespaceId: string
-  /** Protocol associated to the Credential. */
+  /** Protocol associated with the credentials. */
   protocol: NamespaceProtocol
   /**
-   * Credentials file used to connect to the NATS service.
+   * Object containing the credentials, if the credentials are for a NATS
+   * namespace.
    *
    * One-of ('credentialType'): at most one of 'natsCredentials',
    * 'sqsSnsCredentials' could be set.
    */
   natsCredentials?: CredentialNATSCredsFile
   /**
-   * Credential used to connect to the SQS/SNS service.
+   * Object containing the credentials and their metadata, if the credentials
+   * are for an SQS/SNS namespace.
    *
    * One-of ('credentialType'): at most one of 'natsCredentials',
    * 'sqsSnsCredentials' could be set.
@@ -56,26 +58,27 @@ export interface CredentialNATSCredsFile {
 
 /** Credential.sqssns creds. */
 export interface CredentialSQSSNSCreds {
-  /** ID of the key. */
+  /** Access key ID. */
   accessKey: string
-  /** Secret value of the key. */
+  /** Secret key ID. */
   secretKey?: string
-  /** List of permissions associated to this Credential. */
+  /** Permissions associated with these credentials. */
   permissions?: Permissions
 }
 
 /** Credential summary. */
 export interface CredentialSummary {
-  /** Credential ID. */
+  /** ID of the credentials. */
   id: string
-  /** Credential name. */
+  /** Name of the credentials. */
   name: string
-  /** Namespace containing the Credential. */
+  /** Namespace containing the credentials. */
   namespaceId: string
-  /** Protocol associated to the Credential. */
+  /** Protocol associated with the credentials. */
   protocol: NamespaceProtocol
   /**
-   * Credential used to connect to the SQS/SNS service.
+   * Object containing the credentials and their metadata, if the credentials
+   * are for an SQS/SNS namespace.
    *
    * One-of ('credentialType'): at most one of 'sqsSnsCredentials' could be set.
    */
@@ -84,25 +87,25 @@ export interface CredentialSummary {
 
 /** Credential summary.sqssns creds. */
 export interface CredentialSummarySQSSNSCreds {
-  /** ID of the key. */
+  /** Access key ID. */
   accessKey: string
-  /** List of permissions associated to this Credential. */
+  /** Permissions associated with these credentials. */
   permissions?: Permissions
 }
 
 /** List credentials response. */
 export interface ListCredentialsResponse {
-  /** Total number of existing Credentials. */
+  /** Total count of existing credentials (matching any filters specified). */
   totalCount: number
-  /** A page of Credentials. */
+  /** Credentials on this page. */
   credentials: CredentialSummary[]
 }
 
 /** List namespaces response. */
 export interface ListNamespacesResponse {
-  /** Total number of existing Namespaces. */
+  /** Total count of existing namespaces (matching any filters specified). */
   totalCount: number
-  /** A page of Namespaces. */
+  /** Namespaces on this page. */
   namespaces: Namespace[]
 }
 
@@ -112,13 +115,13 @@ export interface Namespace {
   id: string
   /** Namespace name. */
   name: string
-  /** Endpoint of the service matching the Namespace protocol. */
+  /** Endpoint of the service matching the namespace's protocol. */
   endpoint: string
   /** Namespace protocol. */
   protocol: NamespaceProtocol
-  /** Project containing the Namespace. */
+  /** Project ID of the Project containing the namespace. */
   projectId: string
-  /** Region where the Namespace is deployed. */
+  /** Region where the namespace is deployed. */
   region: Region
   /** Namespace creation date. */
   createdAt?: Date
@@ -128,11 +131,20 @@ export interface Namespace {
 
 /** Permissions. */
 export interface Permissions {
-  /** Defines if user can publish messages to the service. */
+  /**
+   * Defines whether the credentials bearer can publish messages to the service
+   * (send messages to SQS queues or publish to SNS topics).
+   */
   canPublish?: boolean
-  /** Defines if user can receive messages from the service. */
+  /**
+   * Defines whether the credentials bearer can receive messages from the
+   * service.
+   */
   canReceive?: boolean
-  /** Defines if user can manage the associated resource(s). */
+  /**
+   * Defines whether the credentials bearer can manage the associated resources
+   * (SQS queues or SNS topics or subscriptions).
+   */
   canManage?: boolean
 }
 
@@ -142,15 +154,15 @@ export type ListNamespacesRequest = {
    * config.
    */
   region?: Region
-  /** Will list only the Namespaces owned by the specified organization. */
+  /** Include only namespaces in this Organization. */
   organizationId?: string
-  /** Will list only the Namespaces contained into the specified project. */
+  /** Include only namespaces in this Project. */
   projectId?: string
-  /** Indicate the page number of results to be returned. */
+  /** Page number to return. */
   page?: number
-  /** Maximum number of results returned by page. */
+  /** Maximum number of namespaces to return per page. */
   pageSize?: number
-  /** Field used for sorting results. */
+  /** Order in which to return results. */
   orderBy?: ListNamespacesRequestOrderBy
 }
 
@@ -162,7 +174,10 @@ export type CreateNamespaceRequest = {
   region?: Region
   /** Namespace name. */
   name?: string
-  /** Namespace protocol. */
+  /**
+   * Namespace protocol. You must specify a valid protocol (and not `unknown`)
+   * to avoid an error.
+   */
   protocol: NamespaceProtocol
   /** Project containing the Namespace. */
   projectId?: string
@@ -196,7 +211,7 @@ export type DeleteNamespaceRequest = {
    * config.
    */
   region?: Region
-  /** ID of the Namespace to delete. */
+  /** ID of the namespace to delete. */
   namespaceId: string
 }
 
@@ -206,12 +221,12 @@ export type CreateCredentialRequest = {
    * config.
    */
   region?: Region
-  /** Namespace containing the Credential. */
+  /** Namespace containing the credentials. */
   namespaceId: string
-  /** Credential name. */
+  /** Name of the credentials. */
   name?: string
   /**
-   * List of permissions associated to this Credential.
+   * Permissions associated with these credentials.
    *
    * One-of ('optionalPermissions'): at most one of 'permissions' could be set.
    */
@@ -224,7 +239,7 @@ export type DeleteCredentialRequest = {
    * config.
    */
   region?: Region
-  /** ID of the Credential to delete. */
+  /** ID of the credentials to delete. */
   credentialId: string
 }
 
@@ -234,13 +249,13 @@ export type ListCredentialsRequest = {
    * config.
    */
   region?: Region
-  /** Namespace containing the Credential. */
+  /** Namespace containing the credentials. */
   namespaceId?: string
-  /** Indicate the page number of results to be returned. */
+  /** Page number to return. */
   page?: number
-  /** Maximum number of results returned by page. */
+  /** Maximum number of credentials to return per page. */
   pageSize?: number
-  /** Field used for sorting results. */
+  /** Order in which to return results. */
   orderBy?: ListCredentialsRequestOrderBy
 }
 
@@ -250,12 +265,12 @@ export type UpdateCredentialRequest = {
    * config.
    */
   region?: Region
-  /** ID of the Credential to update. */
+  /** ID of the credentials to update. */
   credentialId: string
-  /** Credential name. */
+  /** Name of the credentials. */
   name?: string
   /**
-   * List of permissions associated to this Credential.
+   * Permissions associated with these credentials.
    *
    * One-of ('optionalPermissions'): at most one of 'permissions' could be set.
    */
@@ -268,6 +283,6 @@ export type GetCredentialRequest = {
    * config.
    */
   region?: Region
-  /** ID of the Credential to get. */
+  /** ID of the credentials to get. */
   credentialId: string
 }