Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sdk.anghami.com/llms.txt

Use this file to discover all available pages before exploring further.

The SDK is versioned at the proto package level, not at the SDK or repo level. Every package is sdk.{service}.v1. Breaking changes ship as v2 packages alongside v1 until consumers migrate.

​
What’s stable

  • v1 packages are stable. Once a message, field, enum value, or RPC ships in v1, it does not change incompatibly.
  • make breaking enforces this in CI. A PR that introduces a breaking change to v1 fails until reverted.
  • Generated code is regenerated, not rewritten. A make generate run on the same proto produces byte-stable output (within tooling versions).

​
What “breaking” means here

buf enforces the strict definition. The non-exhaustive list:
  • Removing or renaming a field, message, enum, or RPC.
  • Changing a field’s type or number.
  • Changing an enum value’s number.
  • Removing an enum value (renaming is also breaking).
  • Adding a required validation to a previously optional field.
Non-breaking, always allowed:
  • Adding new optional fields, messages, RPCs, or enum values.
  • Adding new validation rules that loosen existing constraints.
  • Improving comments and descriptions.

​
Adding new things

When we ship a new service, RPC, or field:
  • It appears in the bundled OpenAPI spec automatically.
  • Generated TypeScript / Go / Swift / Java / Python clients pick it up on the next regeneration.
  • Existing callers are unaffected.
There is no version pinning per RPC — clients always speak the current v1 shape of the service.

​
Deprecation flow

Eventually, an API surface needs to evolve in a way v1 cannot accommodate. The flow:
  1. v2 package introduced alongside v1. Both ship in parallel.
  2. v1 operations marked deprecated via proto field/RPC comments.
  3. OpenAPI surfaces the deprecation. Generated docs and the bundled spec mark v1 operations as deprecated: true.
  4. Migration window. Typically 6–12 months, depending on the surface area touched.
  5. v1 removed in a separate, well-announced release.
The SDK has not yet had to remove a v1 — when it does, you will see deprecation notices in the changelog and OpenAPI months before removal.

​
Generated client packaging

LanguagePackagePinning
Gogithub.com/anghami/sdk/apiPin a commit / tag
TypeScript@anghami/sdkPin a version range
SwiftAnghamiSDK (SPM)Pin a version tag
Javacom.anghami:anghami-sdkPin via Gradle
Pythonanghami-sdkPin via pip
Pin to a specific tag in production. Within v1, upgrades are safe.

​
CI gates

Every PR runs:
  • buf lint — STANDARD + COMMENTS rules.
  • buf breaking --against main — no breaking changes to v1.
  • make generate — verifies the generated artifacts match the protos.
If any of these fail, the PR cannot merge. This is what keeps v1 stable.