feat:Update OpenAPI Specification for Jina Embedding Serving API to 0.1.80 #62
Conversation
WalkthroughThe changes involve an update to the OpenAPI specification for the Jina Embedding Serving API, transitioning the version from Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant API
participant Schema
Client->>API: Request to /v1/classify
API->>Schema: Validate request
Schema-->>API: Validation result
API-->>Client: Response with classification result
Client->>API: Request to /v1/train
API->>Schema: Validate request
Schema-->>API: Validation result
API-->>Client: Response with training status
Client->>API: Request to deprecated /v1/multi-embeddings
API-->>Client: Warning about deprecation
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
coderabbitai
bot
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (4)
src/libs/Jina/openapi.yaml (4)
Line range hint
377-377: Endpoint deprecation noted, consider adding migration guidance.The
/v1/multi-embeddingsendpoint has been marked as deprecated. This is a good practice for phasing out old functionality. However, to assist users in transitioning away from this endpoint, consider adding:
- A deprecation notice in the endpoint description.
- Information about alternative endpoints or methods that should be used instead.
- A timeline for when this endpoint will be removed completely, if applicable.
Line range hint
458-470: Improved BulkEmbeddingJobResponse schema with additional metadata.The
BulkEmbeddingJobResponseschema has been enhanced with new properties:
user_email: Provides user identification for the job.created_at: Indicates when the job was created.completed_at: Shows when the job was completed.These additions improve the tracking and auditing capabilities for bulk embedding jobs. The new fields are well-documented and appropriate for their purpose.
Consider adding a
started_atfield to capture when the job actually began processing, which could be useful for performance analysis and identifying queuing delays.
Line range hint
1-1180: Improved endpoint descriptions enhance API documentation.The descriptions for various endpoints, particularly
/v1/classifyand/v1/train, have been clarified and expanded. These improvements provide more detailed and accurate information about the purpose and expected inputs for each endpoint, which enhances the API's usability and helps developers integrate with the service more effectively.To further improve the documentation:
- Conduct a consistency check across all endpoint descriptions to ensure a uniform level of detail and style.
- Consider adding example requests and responses for each endpoint to further assist developers in understanding the API's behavior.
Line range hint
1-1180: Overall improvements to the Jina Embedding Serving API specification.This update to the OpenAPI specification includes several positive changes:
- Version increment from 0.1.79 to 0.1.80.
- Deprecation of the
/v1/multi-embeddingsendpoint.- Enhanced
BulkEmbeddingJobResponseschema with additional metadata.- Improved descriptions for various endpoints, particularly
/v1/classifyand/v1/train.These changes collectively improve the API's documentation, usability, and functionality. The deprecation of an old endpoint and the addition of new metadata fields in responses indicate ongoing maintenance and feature development.
As the API evolves, consider the following architectural recommendations:
- Implement versioning in the URL path (e.g.,
/v2/embeddings) for major changes to ensure backward compatibility.- Develop a migration guide for users transitioning from deprecated endpoints to new ones.
- Consider implementing a changelog to track and communicate API changes more effectively to users.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
- src/libs/Jina/openapi.yaml (1 hunks)
🧰 Additional context used
🔇 Additional comments (1)
src/libs/Jina/openapi.yaml (1)
5-5: Version update acknowledged.The API version has been incremented from 0.1.79 to 0.1.80, indicating new features or non-breaking changes have been introduced in this update.
Summary by CodeRabbit
New Features
0.1.80, introducing new endpoints.Deprecations
/v1/multi-embeddingsendpoint as deprecated.Documentation Improvements
/v1/classifyand/v1/trainendpoints.