Skip to content

Conversation

@CortiDevOps
Copy link
Contributor

⚠️ TEMPORARY PREVIEW PR ⚠️

This is a temporary PR created to preview changes from the API specifications.
This PR will be closed when the original API specs PR is merged.

A new, final PR will be created after the API specs changes are merged.


🚨 Breaking Change ❗

⚠️ Important Process Information

🎯 Purpose of This PR

This PR can be for:

  1. Discussions and making decisions about future versions - requires production deployment before merge
  2. Fixes to specifications already on production - can be merged directly after approval
  • Approvals from different teams mean that we actually agree with the proposed changes
  • For new features/versions: We can merge only and only when these changes are on production
  • For production fixes: Can be merged directly after approval
  • Main branch is the source of truth for Corti documentation - we want it to have only relevant information

Checklist

I have provided examples for changed:

  • parameters (query and path)
  • fields
  • request bodies
  • response bodies

SDK Styling Rules Compliance

  • Response/Request Naming: Schema names end with Response/Request (e.g., InteractionResponse, not ResponseInteraction)
  • Tag Prefixes: Named schemas use tag prefix based on where they're used:
    • Single tag: CodesAIContext (used only in methods with codes tag)
    • Multiple tags: CommonAIContext (used across different tag groups)
    • Example: If schema is used in codes and interactions tags → use Common prefix
  • Required/Nullable Fields: All schemas have proper required/nullable field definitions, especially return results
  • Operation IDs: Consistent operationId format (tag + method) across all endpoints
  • Field Comments: Meaningful comments for all fields, including data source references
  • Enums: Used wherever possible for better developer experience

Change description

Behavior description
# https://cucumber.io/docs/gherkin/reference/#example
Scenario: Endpoint rejects invalid body
  Given API supports creating resources
  When my request headers are:
    | name         | value            |
    | Content-Type | application/json |

  And I try to create a resource with "<request body>"
  Then endpoint returns "400" with "<response body>"

  Examples:
    | request body   | response body                                        |
    |                | {"error": "invalid JSON"}                            |
    | -              | {"error": "invalid JSON"}                            |
    | 0              | {"error": "invalid request"}                         |
    | ""             | {"error": "invalid request"}                         |
    | null           | {"error": "invalid request"}                         |
    | {}             | {"error": "missing required field X"}                |
    | []             | {"error": "invalid request"}                         |
    | [{"x": 1}, {}] | {"error": "missing required field X for element #1"} |

References

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants