diff options
| author | Christian Cleberg <[email protected]> | 2026-08-02 15:29:33 -0500 |
|---|---|---|
| committer | Christian Cleberg <[email protected]> | 2026-08-02 15:35:23 -0500 |
| commit | fbcb4113f110a7db9cf21d18510cb59c2e90ba23 (patch) | |
| tree | 5a4afda3920f88f61698329c89771bda75fb8ced /Hutch/API_REFERENCE.md | |
| parent | 04fae8d7fb3726b4d1b4c2576ece04766d2afe74 (diff) | |
| download | hutch-main.tar.gz hutch-main.tar.bz2 hutch-main.zip | |
Diffstat (limited to 'Hutch/API_REFERENCE.md')
| -rw-r--r-- | Hutch/API_REFERENCE.md | 146 |
1 files changed, 0 insertions, 146 deletions
diff --git a/Hutch/API_REFERENCE.md b/Hutch/API_REFERENCE.md deleted file mode 100644 index a2888fc..0000000 --- a/Hutch/API_REFERENCE.md +++ /dev/null @@ -1,146 +0,0 @@ -# Sourcehut API Reference - -This document provides context and references for working with SourceHut's APIs. - -## Official Documentation - -The official SourceHut API documentation can be found at: -- **https://man.sr.ht** - Contains links to API reference pages for all *.sr.ht services - -## Services and Their APIs - -### git.sr.ht (Git Repositories) -- **GraphQL API**: https://git.sr.ht/graphql -- **REST API**: https://git.sr.ht/api -- **Scope required**: `REPOSITORIES:RO` (read-only), `REPOSITORIES:RW` (read-write) - -### todo.sr.ht (Ticket Tracking) -- **GraphQL API**: https://todo.sr.ht/graphql -- **REST API**: https://todo.sr.ht/api -- **Scope required**: `TICKETS:RO` (read-only), `TICKETS:RW` (read-write) - -### hg.sr.ht (Mercurial Repositories) -- **GraphQL API**: https://hg.sr.ht/graphql -- **REST API**: https://hg.sr.ht/api -- **Scope required**: `REPOSITORIES:RO` (read-only), `REPOSITORIES:RW` (read-write) - -### lists.sr.ht (Mailing Lists) -- **GraphQL API**: https://lists.sr.ht/graphql -- **REST API**: https://lists.sr.ht/api -- **Scope required**: `LISTS:RO` (read-only), `LISTS:RW` (read-write) - -### builds.sr.ht (CI/CD) -- **GraphQL API**: https://builds.sr.ht/graphql -- **REST API**: https://builds.sr.ht/api -- **Scope required**: `BUILDS:RO` (read-only), `BUILDS:RW` (read-write) - -### meta.sr.ht (User Accounts) -- **GraphQL API**: https://meta.sr.ht/graphql -- **REST API**: https://meta.sr.ht/api -- **Scope required**: `ACCOUNT:RO` (read-only), `ACCOUNT:RW` (read-write) - -## Authentication - -All API requests require a **Personal Access Token** with the appropriate scopes. - -- **Token creation**: https://meta.sr.ht/oauth2/personal-token -- **Token format**: `Bearer <your-token>` in the Authorization header - -## GraphQL Conventions - -### Common Types - -```graphql -# Cursor-based pagination -type Query { - items(cursor: Cursor, filter: Filter): ItemsPage -} - -type ItemsPage { - results: [Item!]! - cursor: Cursor -} - -# Filter structure (varies by service) -input Filter { - search: String - # ... other service-specific filters -} -``` - -### Error Handling - - SourceHut APIs return GraphQL errors in the following format: - -```json -{ - "data": null, - "errors": [ - { - "message": "Error message", - "path": ["query", "field"], - "extensions": { - "code": "ERROR_CODE" - } - } - ] -} -``` - -## Rate Limiting - -- **Rate limits**: Vary by service and authentication status -- **Headers**: Check `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` -- **Unauthenticated**: Lower limits (typically 60 requests/hour) -- **Authenticated**: Higher limits (typically 5000 requests/hour) - -## Development Notes - -### API Exploration - -Use GraphiQL interfaces available at each service's `/graphql` endpoint to: -- Explore the schema -- Test queries -- Understand available fields and types - -### Common Issues - -1. **Filtering**: Some services may not support all filter operations. Check the schema. -2. **Pagination**: Always handle `cursor` properly for pagination. -3. **Caching**: SourceHut APIs may have aggressive caching. Use cache headers appropriately. - -### Example Query Structure - -```graphql -query { - repositories(cursor: $cursor, filter: $filter) { - results { - id - name - description - # ... other fields - } - cursor - } -} - -# Variables -{ - "filter": { - "search": "query string" - } -} -``` - -## Troubleshooting - -1. **401 Unauthorized**: Check token scopes and expiration -2. **403 Forbidden**: Verify you have access to the requested resource -3. **429 Too Many Requests**: Implement proper rate limiting in your client -4. **500 Internal Server Error**: Check if the API is temporarily down - -## Additional Resources - -- SourceHut API Status: https://status.sr.ht -- SourceHut Man Pages: https://man.sr.ht -- IRC: #sr.ht on Libera.Chat |
