Fix REST API documentation #591
Conversation
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
Co-Authored-By: Alex Reibman <[email protected]>
Co-Authored-By: Alex Reibman <[email protected]>
Co-Authored-By: Alex Reibman <[email protected]>
- Add consistent /v2/ prefix to all endpoints - Fix payload structures (session_id instead of id) - Add proper headers (Content-Type with charset, Accept) - Add comprehensive error handling documentation - Update Python example with error handling Co-Authored-By: Alex Reibman <[email protected]>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
⚙️ Control Options:
Add "(aside)" to your comment to have me ignore it. |
devin-ai-integration
bot
changed the title
WalkthroughThis update introduces a comprehensive REST API test script designed to validate various endpoints, such as session creation, event creation, and session updates. The script employs Changes
🔗 Related PRs
InstructionsEmoji Descriptions:
Interact with the Bot:
Execute a command using the format:
Available Commands:
Tips for Using @bot Effectively:
Need More Help?📚 Visit our documentation for detailed guides on using Entelligence.AI. |
![entelligence-ai-pr-reviews[bot]](https://avatars.githubusercontent.com/in/932812?s=60&v=4){kind=small}
| <CodeGroup> | ||
| ```bash curl | ||
| curl -X POST https://api.agentops.ai/v2/update_session \ | ||
| -H "Content-Type: application/json" \ | ||
| -H "Content-Type: application/json; charset=UTF-8" \ | ||
| -H "Accept: */*" \ | ||
| -H "Authorization: Bearer your_jwt_token" \ | ||
| -d '{ | ||
| "session": { | ||
| "id": "550e8400-e29b-41d4-a716-446655440000", | ||
| "session_id": "550e8400-e29b-41d4-a716-446655440000", | ||
| "end_timestamp": "2024-03-14T12:05:00Z", | ||
| "end_state": "Success", | ||
| "end_state_reason": "Task successfully completed", |
There was a problem hiding this comment.
Ensure Backward Compatibility for API Payload Change
The change from 'id' to 'session_id' in the API payload is a significant modification that can disrupt existing integrations. This change should be clearly documented and communicated to all API users to prevent unexpected failures.
Actionable Steps:
- Documentation: Update the API documentation to reflect this change and highlight it as a breaking change.
- Communication: Notify all users through appropriate channels (e.g., email, developer portal) about the change and its implications.
- Backward Compatibility: Consider implementing a temporary backward compatibility layer that accepts both 'id' and 'session_id' to give users time to transition.
- Migration Guide: Provide a detailed migration guide to assist users in updating their integrations.
These steps will help mitigate the impact of this change and ensure a smoother transition for users. 📢
docs/v1/integrations/rest.mdx
Outdated
| <CodeGroup> | ||
| ```bash curl | ||
| curl -X POST https://api.agentops.ai/v2/create_events \ | ||
| -H "Content-Type: application/json" \ | ||
| -H "Content-Type: application/json; charset=UTF-8" \ | ||
| -H "Accept: */*" \ | ||
| -H "Authorization: Bearer your_jwt_token" \ | ||
| -d '{ | ||
| "events": [ | ||
| { | ||
| "type": "llm", | ||
| "event_type": "llm", | ||
| "init_timestamp": "2024-03-14T12:01:00Z", | ||
| "end_timestamp": "2024-03-14T12:01:02Z", | ||
| "session_id": "550e8400-e29b-41d4-a716-446655440000", | ||
| "model": "gpt-4", | ||
| "prompt": [ | ||
| {"role": "system", "content": "You are a helpful assistant"}, |
There was a problem hiding this comment.
Potential Breaking Change in JSON Payload Key
The change from 'type' to 'event_type' in the JSON payload is a significant modification that could lead to breaking changes if the receiving API is not updated to handle the new key. This could result in failures in data processing or rejection of requests.
Actionable Steps:
- Verify API Compatibility: Confirm with the API documentation or the API development team that the change from 'type' to 'event_type' is intentional and supported.
- System Update: Ensure that all parts of the system interacting with this API are updated to use 'event_type' instead of 'type'.
- Testing: Conduct thorough testing to ensure that the change does not introduce any regressions or failures in the system.
This change is critical and should be handled with caution to avoid disruptions in service.
Co-Authored-By: Alex Reibman <[email protected]>
Co-Authored-By: Alex Reibman <[email protected]>
Co-Authored-By: Alex Reibman <[email protected]>
Co-Authored-By: Alex Reibman <[email protected]>
Co-Authored-By: Alex Reibman <[email protected]>
Co-Authored-By: Alex Reibman <[email protected]>
Co-Authored-By: Alex Reibman <[email protected]>
Co-Authored-By: Alex Reibman <[email protected]>
| <CodeGroup> | ||
| ```bash curl | ||
| curl -X POST https://api.agentops.ai/v2/update_session \ | ||
| -H "Content-Type: application/json" \ | ||
| -H "Content-Type: application/json; charset=UTF-8" \ | ||
| -H "Accept: */*" \ | ||
| -H "Authorization: Bearer your_jwt_token" \ | ||
| -d '{ | ||
| "session": { | ||
| "id": "550e8400-e29b-41d4-a716-446655440000", | ||
| "session_id": "550e8400-e29b-41d4-a716-446655440000", | ||
| "end_timestamp": "2024-03-14T12:05:00Z", | ||
| "end_state": "Success", | ||
| "end_state_reason": "Task successfully completed", |
There was a problem hiding this comment.
Potential Breaking Change in JSON Structure
The change from 'id' to 'session_id' in the JSON structure is a significant modification that could lead to compatibility issues. This change might break existing functionality if other parts of the codebase or external systems rely on the original 'id' field.
Actionable Steps:
- Review Dependencies: Thoroughly review all parts of the codebase and any external systems that interact with this JSON structure to ensure they are updated to use 'session_id' instead of 'id'.
- Backward Compatibility: Consider implementing a backward compatibility layer or a migration path to handle systems that still expect the 'id' field.
- Testing: Conduct comprehensive testing to ensure that the change does not introduce any regressions or unexpected behavior.
- Documentation: Update any relevant documentation to reflect this change, ensuring that all stakeholders are aware of the new structure.
By following these steps, you can mitigate the risk of breaking existing functionality and ensure a smooth transition to the new JSON structure. 🚀
🔍 Review Summary
Purpose
To enhance testing reliability and documentation clarity in the REST API integration for developers. This update includes a comprehensive REST API test script, revised API documentation, and fixes critical database constraint requirements.
Changes
Critical Fixes
New Feature
tests/test_rest_api.pyTest Enhancements
requests_mockto simulate API responsesDocumentation Updates
Impact
Link to Devin run: https://app.devin.ai/sessions/cd9b1ff1a5ad4a8da4519e32039d768c