Skip to content

Overhaul API documentation#42

Merged
ericmj merged 1 commit intohexpm:mainfrom
maennchen:jm/api-doc-update
Apr 8, 2026
Merged

Overhaul API documentation#42
ericmj merged 1 commit intohexpm:mainfrom
maennchen:jm/api-doc-update

Conversation

@maennchen
Copy link
Copy Markdown
Contributor

Summary

  • Update apiary.apib to match actual API responses
  • Add missing endpoints and fix incorrect schemas
  • Document client implementation requirements in endpoints.md

apiary.apib changes

  • Add API Index, Organizations, and OAuth2 Device Authorization Grant
  • Update authentication docs (OAuth2 tokens, API keys, deprecate Basic Auth)
  • Fix response schemas: User, Package, Release, Key, Repository
  • Add missing endpoints: audit logs, delete release, get docs, short_url, auth
  • Fix delete key response code (200 with body, not 204)
  • Fix curl formatting and API Blueprint semantic issues

endpoints.md changes

  • Add Mirroring section
  • Add Client Implementation Reference documenting which endpoints are used by Mix, rebar3, Gleam, and ORT

Closes #8, #18, #29, #30, #31, #36

apiary.apib:
- Add API Index endpoint
- Add Organizations section with all endpoints
- Add OAuth2 Device Authorization Grant documentation
- Update authentication docs (OAuth2 tokens, API keys, deprecate Basic Auth)
- Fix response schemas to match actual API responses:
- User: add full_name, handles, packages fields
- Package: add repository, latest_version, latest_stable_version, configs,
  retirements, owners; fix downloads to include recent
- Release: change dependencies to requirements, add checksum, configs,
  publisher, meta.app, meta.elixir, retirement
- Key: fix revoke_at typo, add last_use, authing_key
- Repository: remove incorrect public, active, billing_active fields
- Add missing endpoints: audit logs, delete release, get single owner,
  delete all keys, organization keys, short_url, auth, get docs
- Fix delete key response code (200 with body, not 204)
- Add retirement examples using oidcc package
- Fix curl formatting (use fenced code blocks)
- Fix API Blueprint semantic issues

endpoints.md:
- Add Mirroring section
- Add Client Implementation Reference with endpoint tables for:
  dependency resolution, publishing, retirement, ownership, authentication,
  API key management, package information, SBoM generation, documentation
  download, and user management
- Document which endpoints each client uses (Mix, rebar3, Gleam, ORT)

Closes hexpm#8, hexpm#18, hexpm#29, hexpm#30, hexpm#31, hexpm#36
@maennchen maennchen force-pushed the jm/api-doc-update branch from ee437b2 to fc12b6e Compare April 7, 2026 19:00
@ericmj
Copy link
Copy Markdown
Member

ericmj commented Apr 8, 2026

Thank you! 💜

@ericmj ericmj merged commit 3dd205d into hexpm:main Apr 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document how mirroring can be done

3 participants