Description
Motivation
Our API can definitely use some better documentation, and we'd love to get some help doing it.
First time contributors welcome!
This is a great way to get your first open source contribution (to PostHog or ever!).
If you get a pull request merged for this, we will:
- Send you a gift card for some cool merch
- Give you a digital contributor card on our Contributors page
- Add your avatar to our main repo README
Endpoints needing documentation
Here are some endpoints we could use documentation for:
/api/projects/api/action/api/insight/api/organizations📖 Example Request & Response/api/insight/trend/api/insight/session/api/insight/retention/api/insight/path/api/event/sessions
And some that could use better/more structured docs:
- https://posthog.com/docs/api/elements
- https://posthog.com/docs/api/events
- https://posthog.com/docs/api/trends
- https://posthog.com/docs/api/user
- https://posthog.com/docs/api/feature-flags
- https://posthog.com/docs/api/cohorts
Important
These endpoints refer to the PostHog platform. The easiest way to get started with PostHog and try these is by creating an account at https://app.posthog.com. Inspecting network requests on the PostHog UI is a great way to understand how our API works - and so is looking at the code.
Using our API requires a Personal API Key.
How to write documentation for an endpoint
When you pick an endpoint, you don't need to write documentation for all possible request types. We'd definitely appreciate you doing so, but we'll accept PRs that document a specific request type for an endpoint. It's more important that the documentation is good and well-structured than poorly documenting a lot of stuff.
💡 To write the docs, you should follow the example of our annotations endpoint docs.
Structure
<Endpoint endpoint='/api/annotation' allowedMethods={['get']} />
Description of the endpoint.
<HiddenSection headingType='h4' title='Query Parameters'>
A table of parameters goes here.
</HiddenSection>
<HiddenSection headingType='h4' title='Example'>
Example request and response go here.
</HiddenSection>
<hr /><br />The following structure should be used for documenting an endpoint. Refer to this file for more insight.
GET requests should have a 'Query Parameters' section (if applicable), and POST and PATCH requests should have 'Request Body' instead. Both should provide an example request and response.
Questions?
If you have any questions, feel free to reach out on Slack or leave a comment on this issue.