add endpoint to create multiple status page subscribers #2
Conversation
There was a problem hiding this comment.
Pull request overview
This pull request adds a new bulk endpoint for creating multiple status page subscribers in a single API request. The endpoint supports partial success scenarios where some subscribers may be created successfully while others fail.
Changes:
- Added new
/v1/{page_id}/subscribers/bulkPOST endpoint that accepts up to 100 subscribers per request - Implemented four new schemas:
BulkAddSubscribersRequest,BulkAddSubscribersResponse,BulkCreatedSubscriber, andBulkFailedSubscriberto support bulk operations - Added support for partial success with detailed results for both successful and failed subscriber creations
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 12 comments.
| File | Description |
|---|---|
| instatus.yaml | Added bulk subscriber endpoint definition and associated request/response schemas |
| instatus.json | JSON representation of the same endpoint and schema definitions for consistency |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| email to confirm their subscription. Applies to all subscribers in | ||
| the batch. This is a paid feature. |
There was a problem hiding this comment.
The autoConfirm property at the bulk request level creates ambiguity with the autoConfirm property that already exists in AddSubscriberRequest. If a subscriber in the array has autoConfirm: false but the bulk request has autoConfirm: true, it's unclear which takes precedence. Consider either removing the bulk-level autoConfirm and relying on the individual subscriber settings, or documenting that the bulk-level setting overrides individual settings.
| email to confirm their subscription. Applies to all subscribers in | |
| the batch. This is a paid feature. | |
| email to confirm their subscription. When this field is provided | |
| at the bulk request level, it applies to all subscribers in the | |
| batch and overrides any `autoConfirm` value specified on individual | |
| subscriber objects. If omitted, the `autoConfirm` setting of each | |
| `AddSubscriberRequest` is used. This is a paid feature. |
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/BulkAddSubscribersResponse" |
There was a problem hiding this comment.
The endpoint only defines a 200 response but doesn't include error responses for common failure scenarios. Consider adding response definitions for 400 (bad request, e.g., invalid payload or exceeds 100 limit), 401 (unauthorized), and 404 (page not found) to properly document the API behavior.
| $ref: "#/components/schemas/BulkAddSubscribersResponse" | |
| $ref: "#/components/schemas/BulkAddSubscribersResponse" | |
| "400": | |
| description: Bad request - invalid payload or exceeded maximum of 100 subscribers per request | |
| "401": | |
| description: Unauthorized - missing or invalid authentication credentials | |
| "404": | |
| description: Not found - the specified status page does not exist |
| type: integer | ||
| description: The index of the subscriber in the original request array. | ||
| subscriber: | ||
| type: object |
There was a problem hiding this comment.
The subscriber field is defined as a generic object without a schema reference. This makes it unclear what structure will be returned. Consider using $ref: "#/components/schemas/AddSubscriberRequest" or defining the specific properties to provide clear API documentation.
| type: object | |
| $ref: "#/components/schemas/AddSubscriberRequest" |
| "BulkCreatedSubscriber": { | ||
| "type": "object", | ||
| "properties": { | ||
| "id": { | ||
| "type": "string" | ||
| }, | ||
| "email": { | ||
| "type": "string", | ||
| "nullable": true | ||
| }, | ||
| "phone": { | ||
| "type": "string", | ||
| "nullable": true | ||
| }, | ||
| "name": { | ||
| "type": "string", | ||
| "nullable": true | ||
| }, | ||
| "confirmed": { | ||
| "type": "boolean" | ||
| }, | ||
| "all": { | ||
| "type": "boolean" | ||
| }, | ||
| "site": { | ||
| "type": "object", | ||
| "properties": { | ||
| "id": { | ||
| "type": "string" | ||
| } | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
The BulkCreatedSubscriber schema is missing several fields that are present in SubscriberDetail, such as components, webhook, webhookEmail, language, and other integration fields. This inconsistency could be confusing for API consumers who expect similar data between single and bulk creation responses. Consider either including these fields or documenting why they are intentionally omitted in the bulk response.
| properties: | ||
| subscribers: | ||
| type: array | ||
| description: Array of subscriber objects to create. |
There was a problem hiding this comment.
The subscribers array should have a minItems: 1 constraint. Allowing an empty array would make the request meaningless and could cause unexpected behavior. Add a minimum constraint to ensure at least one subscriber is provided.
| description: Array of subscriber objects to create. | |
| description: Array of subscriber objects to create. | |
| minItems: 1 |
| }, | ||
| "autoConfirm": { | ||
| "type": "boolean", | ||
| "description": "Whether subscribers are automatically confirmed or will receive an email to confirm their subscription. Applies to all subscribers in the batch. This is a paid feature." |
There was a problem hiding this comment.
The autoConfirm property at the bulk request level creates ambiguity with the autoConfirm property that already exists in AddSubscriberRequest. If a subscriber in the array has autoConfirm: false but the bulk request has autoConfirm: true, it's unclear which takes precedence. Consider either removing the bulk-level autoConfirm and relying on the individual subscriber settings, or documenting that the bulk-level setting overrides individual settings.
| "description": "Whether subscribers are automatically confirmed or will receive an email to confirm their subscription. Applies to all subscribers in the batch. This is a paid feature." | |
| "description": "Whether subscribers are automatically confirmed or will receive an email to confirm their subscription. When this field is provided at the bulk request level, it applies to all subscribers in the batch and overrides any `autoConfirm` value specified on individual subscribers. This is a paid feature." |
| "subscribers": { | ||
| "type": "array", | ||
| "description": "Array of subscriber objects to create.", | ||
| "maxItems": 100, |
There was a problem hiding this comment.
The subscribers array should have a minItems: 1 constraint. Allowing an empty array would make the request meaningless and could cause unexpected behavior. Add a minimum constraint to ensure at least one subscriber is provided.
| "maxItems": 100, | |
| "maxItems": 100, | |
| "minItems": 1, |
| "$ref": "#/components/schemas/BulkAddSubscribersResponse" | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
The endpoint only defines a 200 response but doesn't include error responses for common failure scenarios. Consider adding response definitions for 400 (bad request, e.g., invalid payload or exceeds 100 limit), 401 (unauthorized), and 404 (page not found) to properly document the API behavior.
| } | |
| } | |
| }, | |
| "400": { | |
| "description": "Bad request - invalid payload or exceeds 100 subscribers per request limit", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "code": { | |
| "type": "string", | |
| "description": "Error code identifying the type of validation error" | |
| }, | |
| "message": { | |
| "type": "string", | |
| "description": "Human-readable description of the error" | |
| } | |
| }, | |
| "required": ["message"] | |
| } | |
| } | |
| } | |
| }, | |
| "401": { | |
| "description": "Unauthorized - missing or invalid API token", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "code": { | |
| "type": "string", | |
| "description": "Error code indicating authentication failure" | |
| }, | |
| "message": { | |
| "type": "string", | |
| "description": "Human-readable description of the authentication error" | |
| } | |
| }, | |
| "required": ["message"] | |
| } | |
| } | |
| } | |
| }, | |
| "404": { | |
| "description": "Not found - the specified status page does not exist", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "code": { | |
| "type": "string", | |
| "description": "Error code indicating the resource was not found" | |
| }, | |
| "message": { | |
| "type": "string", | |
| "description": "Human-readable description of the not found error" | |
| } | |
| }, | |
| "required": ["message"] | |
| } | |
| } | |
| } |
| "type": "object", | ||
| "description": "The subscriber data that was submitted." |
There was a problem hiding this comment.
The subscriber field is defined as a generic object without a schema reference. This makes it unclear what structure will be returned. Consider using $ref: "#/components/schemas/AddSubscriberRequest" or defining the specific properties to provide clear API documentation.
| "type": "object", | |
| "description": "The subscriber data that was submitted." | |
| "description": "The subscriber data that was submitted.", | |
| "allOf": [ | |
| { | |
| "$ref": "#/components/schemas/AddSubscriberRequest" | |
| } | |
| ] |
| "type": "string", | ||
| "description": "Human-readable error message." | ||
| } | ||
| } |
There was a problem hiding this comment.
The error object properties should be marked as required to ensure consistent error reporting. Both code and message are essential for proper error handling and should not be optional.
| } | |
| }, | |
| "required": [ | |
| "code", | |
| "message" | |
| ] |
No description provided.