ulith/pronounss
1
0
Fork 0
forked from mirrors/pronouns.cc
Code Pull requests Activity
pronounss/docs-site/api/index.md
sam d05e1d241c start documentation site
2023-08-20 22:38:53 +02:00

3 KiB
Raw Blame History

API reference

pronouns.cc has a HTTP REST API to query and edit profiles, available at https://pronouns.cc/api.

Versioning

The API is versioned, and versions must be explicitly specified for all endpoints. The current, and only, available version is 1. The version is specified in the request path, like https://pronouns.cc/api/v{version}.

Version Status
1 Default
2 Upcoming

The API version will be incremented for any breaking changes, including:

  • Removing entire endpoints
  • Removing fields from responses
  • Changing the behaviour of fields (in some situations, see below)

However, the following types of changes are not considered breaking:

  • Adding new endpoints
  • Adding new fields to requests or responses (your JSON serializer/deserializer should ignore unknown fields)
  • Forcing fields related to removed features to their default value

Authentication

Tokens can be created here.
Not all endpoints require authentication. For those that do, a token must be provided in the Authorization header. The token may be prefixed with Bearer , but this is not required.

Documentation formatting

The "type" column in tables is formatted as follows:

  • The type used is the Go type, not the JSON type. For example, the documentation will use int for integers and float for floats, even though they are both represented with JSON numbers.
  • A leading ? signifies that the field may be omitted.
  • A trailing ? signifies that the field may be null.

IDs

::: info pronouns.cc is planning a transition to Snowflake IDs. The information below pertains to the current ID format. :::

The API uses xid for unique IDs. These are always serialized as strings. Although xids have timestamp information embedded in them, this is non-trivial to extract. xids are unique across all resources, they are never shared (for example, a user and a member cannot share the same ID).

Users and members also have an additional ID type, sid. These are randomly generated 5 or 6 letter strings, and are used for the prns.cc URL shortener. They can be rerolled once per hour.

Images

The API does not return full URLs to images such as avatars and pride flags. Instead, the URL must be constructed manually using the avatar or hash fields.

The default user and member avatar is served at https://pronouns.cc/default/512.webp. All custom images are served on the base URL https://cdn.pronouns.cc, and are only available in WebP format.

Type Format
User avatar /users/{user.id}/{user.avatar}.webp
Member avatar /members/{member.id}/{member.avatar}.webp
Pride flag /flags/{flag.hash}.webp