Skip to content

Commit cc53312

Browse files
scaleway-botscaleway-bot
authored
docs(fix): reworked mnq api doc (#1631)
1 parent ba57139 commit cc53312

File tree

1 file changed

+59
-50
lines changed

1 file changed

+59
-50
lines changed

‎api/mnq/v1alpha1/mnq_sdk.go‎

Lines changed: 59 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ var (
3939
_ = namegenerator.GetRandomName
4040
)
4141

42-
// API: this API allows you to manage Messaging or Queueing brokers.
42+
// API: this API allows you to manage Scaleway Messaging and Queueing brokers.
4343
// MnQ API (beta).
4444
type API struct {
4545
client *scw.Client
@@ -155,19 +155,19 @@ func (enum *NamespaceProtocol) UnmarshalJSON(data []byte) error {
155155

156156
// Credential: credential.
157157
type Credential struct {
158-
// ID: credential ID.
158+
// ID: ID of the credentials.
159159
ID string `json:"id"`
160-
// Name: credential name.
160+
// Name: name of the credentials.
161161
Name string `json:"name"`
162-
// NamespaceID: namespace containing the Credential.
162+
// NamespaceID: namespace containing the credentials.
163163
NamespaceID string `json:"namespace_id"`
164-
// Protocol: protocol associated to the Credential.
164+
// Protocol: protocol associated with the credentials.
165165
// Default value: unknown
166166
Protocol NamespaceProtocol `json:"protocol"`
167-
// NatsCredentials: credentials file used to connect to the NATS service.
167+
// NatsCredentials: object containing the credentials, if the credentials are for a NATS namespace.
168168
// Precisely one of NatsCredentials, SqsSnsCredentials must be set.
169169
NatsCredentials *CredentialNATSCredsFile `json:"nats_credentials,omitempty"`
170-
// SqsSnsCredentials: credential used to connect to the SQS/SNS service.
170+
// SqsSnsCredentials: object containing the credentials and their metadata, if the credentials are for an SQS/SNS namespace.
171171
// Precisely one of NatsCredentials, SqsSnsCredentials must be set.
172172
SqsSnsCredentials *CredentialSQSSNSCreds `json:"sqs_sns_credentials,omitempty"`
173173
}
@@ -180,51 +180,51 @@ type CredentialNATSCredsFile struct {
180180

181181
// CredentialSQSSNSCreds: credential.sqssns creds.
182182
type CredentialSQSSNSCreds struct {
183-
// AccessKey: ID of the key.
183+
// AccessKey: access key ID.
184184
AccessKey string `json:"access_key"`
185-
// SecretKey: secret value of the key.
185+
// SecretKey: secret key ID.
186186
SecretKey *string `json:"secret_key"`
187-
// Permissions: list of permissions associated to this Credential.
187+
// Permissions: permissions associated with these credentials.
188188
Permissions *Permissions `json:"permissions"`
189189
}
190190

191191
// CredentialSummary: credential summary.
192192
type CredentialSummary struct {
193-
// ID: credential ID.
193+
// ID: ID of the credentials.
194194
ID string `json:"id"`
195-
// Name: credential name.
195+
// Name: name of the credentials.
196196
Name string `json:"name"`
197-
// NamespaceID: namespace containing the Credential.
197+
// NamespaceID: namespace containing the credentials.
198198
NamespaceID string `json:"namespace_id"`
199-
// Protocol: protocol associated to the Credential.
199+
// Protocol: protocol associated with the credentials.
200200
// Default value: unknown
201201
Protocol NamespaceProtocol `json:"protocol"`
202-
// SqsSnsCredentials: credential used to connect to the SQS/SNS service.
202+
// SqsSnsCredentials: object containing the credentials and their metadata, if the credentials are for an SQS/SNS namespace.
203203
// Precisely one of SqsSnsCredentials must be set.
204204
SqsSnsCredentials *CredentialSummarySQSSNSCreds `json:"sqs_sns_credentials,omitempty"`
205205
}
206206

207207
// CredentialSummarySQSSNSCreds: credential summary.sqssns creds.
208208
type CredentialSummarySQSSNSCreds struct {
209-
// AccessKey: ID of the key.
209+
// AccessKey: access key ID.
210210
AccessKey string `json:"access_key"`
211-
// Permissions: list of permissions associated to this Credential.
211+
// Permissions: permissions associated with these credentials.
212212
Permissions *Permissions `json:"permissions"`
213213
}
214214

215215
// ListCredentialsResponse: list credentials response.
216216
type ListCredentialsResponse struct {
217-
// TotalCount: total number of existing Credentials.
217+
// TotalCount: total count of existing credentials (matching any filters specified).
218218
TotalCount uint32 `json:"total_count"`
219-
// Credentials: a page of Credentials.
219+
// Credentials: credentials on this page.
220220
Credentials []*CredentialSummary `json:"credentials"`
221221
}
222222

223223
// ListNamespacesResponse: list namespaces response.
224224
type ListNamespacesResponse struct {
225-
// TotalCount: total number of existing Namespaces.
225+
// TotalCount: total count of existing namespaces (matching any filters specified).
226226
TotalCount uint32 `json:"total_count"`
227-
// Namespaces: a page of Namespaces.
227+
// Namespaces: namespaces on this page.
228228
Namespaces []*Namespace `json:"namespaces"`
229229
}
230230

@@ -234,14 +234,14 @@ type Namespace struct {
234234
ID string `json:"id"`
235235
// Name: namespace name.
236236
Name string `json:"name"`
237-
// Endpoint: endpoint of the service matching the Namespace protocol.
237+
// Endpoint: endpoint of the service matching the namespace's protocol.
238238
Endpoint string `json:"endpoint"`
239239
// Protocol: namespace protocol.
240240
// Default value: unknown
241241
Protocol NamespaceProtocol `json:"protocol"`
242-
// ProjectID: project containing the Namespace.
242+
// ProjectID: project ID of the Project containing the namespace.
243243
ProjectID string `json:"project_id"`
244-
// Region: region where the Namespace is deployed.
244+
// Region: region where the namespace is deployed.
245245
Region scw.Region `json:"region"`
246246
// CreatedAt: namespace creation date.
247247
CreatedAt *time.Time `json:"created_at"`
@@ -251,11 +251,11 @@ type Namespace struct {
251251

252252
// Permissions: permissions.
253253
type Permissions struct {
254-
// CanPublish: defines if user can publish messages to the service.
254+
// CanPublish: defines whether the credentials bearer can publish messages to the service (send messages to SQS queues or publish to SNS topics).
255255
CanPublish *bool `json:"can_publish"`
256-
// CanReceive: defines if user can receive messages from the service.
256+
// CanReceive: defines whether the credentials bearer can receive messages from the service.
257257
CanReceive *bool `json:"can_receive"`
258-
// CanManage: defines if user can manage the associated resource(s).
258+
// CanManage: defines whether the credentials bearer can manage the associated resources (SQS queues or SNS topics or subscriptions).
259259
CanManage *bool `json:"can_manage"`
260260
}
261261

@@ -269,20 +269,21 @@ func (s *API) Regions() []scw.Region {
269269
type ListNamespacesRequest struct {
270270
// Region: region to target. If none is passed will use default region from the config.
271271
Region scw.Region `json:"-"`
272-
// OrganizationID: will list only the Namespaces owned by the specified organization.
272+
// OrganizationID: include only namespaces in this Organization.
273273
OrganizationID *string `json:"-"`
274-
// ProjectID: will list only the Namespaces contained into the specified project.
274+
// ProjectID: include only namespaces in this Project.
275275
ProjectID *string `json:"-"`
276-
// Page: indicate the page number of results to be returned.
276+
// Page: page number to return.
277277
Page *int32 `json:"-"`
278-
// PageSize: maximum number of results returned by page.
278+
// PageSize: maximum number of namespaces to return per page.
279279
PageSize *uint32 `json:"-"`
280-
// OrderBy: field used for sorting results.
280+
// OrderBy: order in which to return results.
281281
// Default value: created_at_asc
282282
OrderBy ListNamespacesRequestOrderBy `json:"-"`
283283
}
284284

285285
// ListNamespaces: list namespaces.
286+
// 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.
286287
func (s *API) ListNamespaces(req *ListNamespacesRequest, opts ...scw.RequestOption) (*ListNamespacesResponse, error) {
287288
var err error
288289

@@ -328,14 +329,15 @@ type CreateNamespaceRequest struct {
328329
Region scw.Region `json:"-"`
329330
// Name: namespace name.
330331
Name string `json:"name"`
331-
// Protocol: namespace protocol.
332+
// Protocol: namespace protocol. You must specify a valid protocol (and not `unknown`) to avoid an error.
332333
// Default value: unknown
333334
Protocol NamespaceProtocol `json:"protocol"`
334335
// ProjectID: project containing the Namespace.
335336
ProjectID string `json:"project_id"`
336337
}
337338

338339
// CreateNamespace: create a namespace.
340+
// Create a Messaging and Queuing namespace, set to the desired protocol.
339341
func (s *API) CreateNamespace(req *CreateNamespaceRequest, opts ...scw.RequestOption) (*Namespace, error) {
340342
var err error
341343

@@ -387,6 +389,7 @@ type UpdateNamespaceRequest struct {
387389
}
388390

389391
// UpdateNamespace: update the name of a namespace.
392+
// Update the name of a Messaging and Queuing namespace, specified by its namespace ID.
390393
func (s *API) UpdateNamespace(req *UpdateNamespaceRequest, opts ...scw.RequestOption) (*Namespace, error) {
391394
var err error
392395

@@ -427,6 +430,7 @@ type GetNamespaceRequest struct {
427430
}
428431

429432
// GetNamespace: get a namespace.
433+
// 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.
430434
func (s *API) GetNamespace(req *GetNamespaceRequest, opts ...scw.RequestOption) (*Namespace, error) {
431435
var err error
432436

@@ -461,11 +465,12 @@ func (s *API) GetNamespace(req *GetNamespaceRequest, opts ...scw.RequestOption)
461465
type DeleteNamespaceRequest struct {
462466
// Region: region to target. If none is passed will use default region from the config.
463467
Region scw.Region `json:"-"`
464-
// NamespaceID: ID of the Namespace to delete.
468+
// NamespaceID: ID of the namespace to delete.
465469
NamespaceID string `json:"-"`
466470
}
467471

468472
// DeleteNamespace: delete a namespace.
473+
// 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.
469474
func (s *API) DeleteNamespace(req *DeleteNamespaceRequest, opts ...scw.RequestOption) error {
470475
var err error
471476

@@ -498,17 +503,17 @@ func (s *API) DeleteNamespace(req *DeleteNamespaceRequest, opts ...scw.RequestOp
498503
type CreateCredentialRequest struct {
499504
// Region: region to target. If none is passed will use default region from the config.
500505
Region scw.Region `json:"-"`
501-
// NamespaceID: namespace containing the Credential.
506+
// NamespaceID: namespace containing the credentials.
502507
NamespaceID string `json:"namespace_id"`
503-
// Name: credential name.
508+
// Name: name of the credentials.
504509
Name string `json:"name"`
505-
// Permissions: list of permissions associated to this Credential.
510+
// Permissions: permissions associated with these credentials.
506511
// Precisely one of Permissions must be set.
507512
Permissions *Permissions `json:"permissions,omitempty"`
508513
}
509514

510-
// CreateCredential: create a set of credentials.
511-
// Create a set of credentials for a specific namespace.
515+
// CreateCredential: create credentials.
516+
// 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.
512517
func (s *API) CreateCredential(req *CreateCredentialRequest, opts ...scw.RequestOption) (*Credential, error) {
513518
var err error
514519

@@ -548,11 +553,12 @@ func (s *API) CreateCredential(req *CreateCredentialRequest, opts ...scw.Request
548553
type DeleteCredentialRequest struct {
549554
// Region: region to target. If none is passed will use default region from the config.
550555
Region scw.Region `json:"-"`
551-
// CredentialID: ID of the Credential to delete.
556+
// CredentialID: ID of the credentials to delete.
552557
CredentialID string `json:"-"`
553558
}
554559

555560
// DeleteCredential: delete credentials.
561+
// 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.
556562
func (s *API) DeleteCredential(req *DeleteCredentialRequest, opts ...scw.RequestOption) error {
557563
var err error
558564

@@ -585,18 +591,19 @@ func (s *API) DeleteCredential(req *DeleteCredentialRequest, opts ...scw.Request
585591
type ListCredentialsRequest struct {
586592
// Region: region to target. If none is passed will use default region from the config.
587593
Region scw.Region `json:"-"`
588-
// NamespaceID: namespace containing the Credential.
594+
// NamespaceID: namespace containing the credentials.
589595
NamespaceID *string `json:"-"`
590-
// Page: indicate the page number of results to be returned.
596+
// Page: page number to return.
591597
Page *int32 `json:"-"`
592-
// PageSize: maximum number of results returned by page.
598+
// PageSize: maximum number of credentials to return per page.
593599
PageSize *uint32 `json:"-"`
594-
// OrderBy: field used for sorting results.
600+
// OrderBy: order in which to return results.
595601
// Default value: id_asc
596602
OrderBy ListCredentialsRequestOrderBy `json:"-"`
597603
}
598604

599605
// ListCredentials: list credentials.
606+
// 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**).
600607
func (s *API) ListCredentials(req *ListCredentialsRequest, opts ...scw.RequestOption) (*ListCredentialsResponse, error) {
601608
var err error
602609

@@ -639,16 +646,17 @@ func (s *API) ListCredentials(req *ListCredentialsRequest, opts ...scw.RequestOp
639646
type UpdateCredentialRequest struct {
640647
// Region: region to target. If none is passed will use default region from the config.
641648
Region scw.Region `json:"-"`
642-
// CredentialID: ID of the Credential to update.
649+
// CredentialID: ID of the credentials to update.
643650
CredentialID string `json:"-"`
644-
// Name: credential name.
651+
// Name: name of the credentials.
645652
Name *string `json:"name"`
646-
// Permissions: list of permissions associated to this Credential.
653+
// Permissions: permissions associated with these credentials.
647654
// Precisely one of Permissions must be set.
648655
Permissions *Permissions `json:"permissions,omitempty"`
649656
}
650657

651-
// UpdateCredential: update a set of credentials.
658+
// UpdateCredential: update credentials.
659+
// 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.
652660
func (s *API) UpdateCredential(req *UpdateCredentialRequest, opts ...scw.RequestOption) (*Credential, error) {
653661
var err error
654662

@@ -688,11 +696,12 @@ func (s *API) UpdateCredential(req *UpdateCredentialRequest, opts ...scw.Request
688696
type GetCredentialRequest struct {
689697
// Region: region to target. If none is passed will use default region from the config.
690698
Region scw.Region `json:"-"`
691-
// CredentialID: ID of the Credential to get.
699+
// CredentialID: ID of the credentials to get.
692700
CredentialID string `json:"-"`
693701
}
694702

695-
// GetCredential: get a set of credentials.
703+
// GetCredential: get credentials.
704+
// 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.
696705
func (s *API) GetCredential(req *GetCredentialRequest, opts ...scw.RequestOption) (*Credential, error) {
697706
var err error
698707

0 commit comments

Comments
 (0)