leonhard-s/ps2-api-docs

Unofficial OpenAPI specification and documentation provider for the PlanetSide 2 API.

PS2 API Docs

Unofficial OpenAPI specification and documentation provider for the PlanetSide 2 API.

---

This repository maintains a full list of all collections in the PlanetSide 2 API. Currently, only the REST endpoint is documented. A WebSocket API reference may be added in a later version.

API Preview

An HTML version of this specification is automatically built using ReDoc and hosted at this location.

Usage

This repository defines the API endpoints according to the OpenAPI 3.1 speficiation, which manifests itself as a YAML or JSON document defining available server endpoints, paths/routes, schemata and example payloads.

If your use case does not support multi-file OpenAPI documents or you are restricted to a single file, you can use the single-file JSON version. This is also the file used to generate the HTML preview linked above.

Note: Please be aware that the generated spec is not yet stable and may change in the future (see #9 for details).

Extensions

Note: Vendor extensions are not yet finalized and may change in the near future. See #7 for details.

The OpenAPI standard allows the insertion of custom fields into the standard. These fields are prefixed with x- and listed below:

• x-cast-to

  The Census API returns most values as strings. This field defines the type to which the value should be cast. Note that casting to boolean requires special handling of the strings "0" and "NULL", which may be interpreted as truthy values in some languages such as Python.

• x-reference-to

  For ID fields, this field defines the qualified names of a collection that can be joined to this field as an array of strings.

  For example, the property outfit.leader_character_id has the value character.character_id in its x-reference-to list.

  This field may be used to dynamically create or validate joins to related data.

Contributing

Contributions of any form are always appreciated and vital to the project, be it corrections, more specific examples, edge cases or other improvements.

If you are unfamiliar with the OpenAPI syntax, feel free to just create an issue with your changes and have someone else sort it out.

ps2-api-docs's Issues

Consider simplifying OpenAPI `paths`

We are currently listing the paths for each collection individually. This gives more flexibility with collection-specific parameters, but also adds a lot of boilerplate code. To be investigated.

Update LICENSE

This project is currently licensed under MIT, which has some attribution and licensing implications.

For a project like this, these are an unnecessary hurdle. The Unlicense or WTFPL feel more appropriate here.

Break up API spec definition into smaller files

This will be more maintainable and makes it easier to navigate on devices that do not appreciate loading 20k lines of source code.

Define vendor extensions

The current spec uses a slightly inconsistent mix of vendor (x-) fields that should be tidied up and documented.

Examples

• x-cast-to is not consistently placed and should always be next to the type field. Could also be renamed to x-type-cast-to or other variants whose intent is clearer

• x-reference-to should not contain the game namespace, only the fields. Another name could be considered too, though it is worth noting that these are not only used for primary keys

• x-deprecated or x-unused could be used to document fields that should not be exposed to users of generated code

• x-deprecated should point to alternatives

Update CI job logic to not rely on a failing step

The CI job for generating the monolithic JSON spec currently uses a git diff job to determine whether there are any changes to be committed. This works well, but since any job has failed the entire workflow is flagged as failed in the commit overview.

Merge with ps2-ess-api repository

The WebSocket API is now documented at https://github.com/leonhard-s/ps2-ess-api. Long-term, the two projects should be merged and a single documentation site built, perhaps with a custom domain.

Things to look at:

• How to separate the two specs on the code level
• If we can use the newer Redocly stylesheets if we built the spec via GitHub pages (optional)
• How to get the styling of the HTML specs to be remotely similar (very optional)

PS2 collection documentation

I want to provide explicit documentation of most PS2 endpoints by overriding the path parameter. Common parameters like query commands would be documented in a templated /get/{game}/{collection} endpoint, while we can provide overrides and extra information via /get/{ps2namespace}/character as required.

These endpoints will contain some explicit parameters (such as the primary ID field or name) for filtering, but I am doubtful that listing every subkey explicitly is particularly useful (ps2/character.times.last_save_date, ps2/character.certs.progress_to_next, etc.)

Initial version will focus on primary keys and other common queries to allow for API spec linking, i.e. being able to connect ps2/character.faction_id to the ps2/faction collection.

Switch to component-based API spec definition

The templated YAML-to-JSON converter was a nice idea, but it proved to not aid maintainability and additionally resulted in an exceptionally large and expensive-to-parse JSON spec, slowing down (or breaking) viewers.

D-R-Y is nice, but we should use the tools available in OpenAPI rather than relying on custom tooling to generate half the code in place.

OpenAPI 3.1

Move API spec & docs hosting to GitHub Pages

The current read-the-docs workaround relies on a monolithic spec to load the API definition. A multi-file spec would fail; the relative path resolution does not work through raw.githubusercontent.com.

Document experimental `~` RegEx operator

I added a regex not contains operator (~) to queries. I have not documented this new operator yet, as I wanted it to soak test for a while.

Here is an example query: https://census.daybreakgames.com/s:example/get/ps2:v2/experience?c:limit=1000&description=~HIVE

Document ESS endpoints

OpenAPI is still primarily targeting REST APIs, and support for WebSocket or other streaming protocols seems an open issue that may never get first-class treatment.

A workaround for us would be to instead model these via a REST endpoint at push.planetside2.com/streaming, and faking the actual responses through POST/GET messages, with a big blinking "this is just a dummy" light flashing on top.

Alternatively, we could create and maintain a separate AsyncAPI spec that is able to model WebSocket subscriptions and messages correctly.

Update tag group & endpoint names, documentation

The current tags mostly mirror the base name of the endpoint URL. This doesn't really help users not familiar with them, and it hurts ones that do. Either we just use the collection name, or we describe it more clearly.

The same goes for endpoint descriptions; they are generally too vague for experienced users and not specific enough for new ones.

Update `metagame_event` table

As of 2023-09-14, the metagame_event collection possesses an additional duration_minutes field containing the alert duration in minutes.

Provide alternate API spec variants

The reference spec will be technically correct and cover both the source and cast type for all fields, as well as provide any documentation required to use the API.

However, this compromises all use cases. Instead, we could provide different "releases" of the same version of the spec, for different deployments:

• The documentation spec on ReadTheDocs could use the cast types for readability, rather than typing everything as string (even if this is correct)
• Client code may want a smaller, lower-bandwidth version of the spec that does away with examples and documentation
• There could still be use cases for which a full monolith is better suited than the multi-file layout the repo will use/should be using