Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

overhaul of docs, added many pages #39

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

overhaul of docs, added many pages #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ab35b34
initial commit
Jan 31, 2023
0b09468
added new pages
Jan 31, 2023
c740ab7
added images
Jan 31, 2023
b55883f
smol change to design guide
Jan 31, 2023
288c8db
dang file extension capitalization
Feb 1, 2023
373537a
dang file extension capitalization
Feb 1, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
209 changes: 138 additions & 71 deletions docs/api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,23 +5,30 @@ title: Public API

# Public API

## API Endpoint: `https://public-api.gitpoap.io/`
## API Endpoint

#### `https://public-api.gitpoap.io/`

<br />

If you have any questions, comments, or suggestions, please reach out to us via [twitter](https://twitter.com/gitpoap),
our community [Discord Server](https://gitpoap.io/discord), or send us a message at team at gitpoap.io
our community [Discord Server](https://gitpoap.io/discord), or send us a message at team@gitpoap.io

<br />

## Version 1
## _Version 1_

**Note that the public API limits individual IPs to a
maximum of 100 requests within a 5 minute window.**
_Note that the public API limits individual IPs to a
maximum of 100 requests within a 5 minute window._

### `GET /v1/poap/:poapTokenId/is-gitpoap`

This endpoint allows users to query whether some `poapTokenId` is a GitPOAP or not.
<details>
<summary>
<h3>Check if a POAP is a GitPOAP</h3>
<code>GET /v1/poap/:poapTokenId/is-gitpoap</code>
</summary>
<div>
This endpoint allows users to query whether some `poapTokenId` is a GitPOAP or not.
In the case that the `poapTokenId` corresponds to some claimed GitPOAP, the API will return
something like:

Expand All @@ -40,27 +47,33 @@ And in the case that it is not a GitPOAP:
}
```

<br />
</div>
</details>

### `GET /v1/poap/gitpoap-ids`
<details>
<summary>
<h3>Return GitPOAP Token IDs</h3>
<code>GET /v1/poap/gitpoap-ids</code>
</summary>
<div>
This endpoint returns all of the POAP Token IDs that are GitPOAPs. It will return data like:

This endpoint returns all of the POAP Token IDs that are GitPOAPs. It will return data like:
```json
{
"poapTokenIds": [
"4637848",
"4638134",
"4641290",
"4641645"
]
"poapTokenIds": ["4637848", "4638134", "4641290", "4641645"]
}
```

<br />

### `GET /v1/poap-event/:poapEventId/is-gitpoap`
</div>
</details>

This endpoint allows users to query whether some `poapEventId` is for GitPOAP project
<details>
<summary>
<h3>Query whether some <code>poapEventId</code> is for GitPOAP project contribution level</h3>
<code>GET /v1/poap-event/:poapEventId/is-gitpoap</code>
</summary>
<div>
This endpoint allows users to query whether some `poapEventId` is for GitPOAP project
contribution level. In the case that the `poapEventId` is for a GitPOAP project contribution
level, it will return something like:

Expand All @@ -79,27 +92,34 @@ And in the case that it is not a GitPOAP project contribution level:
}
```

<br />
</div>
</details>

### `GET /v1/poap-event/gitpoap-event-ids`
<details>
<summary>
<h3>Return all POAP Event IDs that are GitPOAP Events</h3>
<code>GET /v1/poap-event/gitpoap-event-ids</code>
</summary>
<div>
This endpoint returns all of the POAP Event IDs that are GitPOAP Events. It will return data like:

This endpoint returns all of the POAP Event IDs that are GitPOAP Events. It will return data like:
```json
{
"poapEventIds": [
37428,
37430,
37556,
37557
]
"poapEventIds": [37428, 37430, 37556, 37557]
}
```

<br />
</div>
</details>

### `GET /v1/poap-event/gitpoap-event-fancy-ids`
<details>
<summary>
<h3>Return all POAP Event Fancy IDs that are GitPOAP Events</h3>
<code>GET /v1/poap-event/gitpoap-event-fancy-ids</code>
</summary>
<div>
This endpoint returns all of the POAP Event Fancy IDs that are GitPOAP Events. It will return data like:

This endpoint returns all of the POAP Event Fancy IDs that are GitPOAP Events. It will return data like:
```json
{
"poapEventFancyIds": [
Expand All @@ -111,32 +131,45 @@ This endpoint returns all of the POAP Event Fancy IDs that are GitPOAP Events. I
}
```

<br />
</div>
</details>

### `GET /v1/gitpoaps/events`
<details>
<summary>
<h3>Query for info on all the GitPOAPs that have been released so far</h3>
<code>GET /v1/gitpoaps/events</code>
</summary>
<div>
This endpoint allows user to query for information on all the GitPOAPs that have been released so far. It will return data in the form:

This endpoint allows user to query for information on all the GitPOAPs that have been released so far. It will return data in the form:
```json
{
"gitPoapEvents": [{
"gitPoapEventId": 32423,
"poapEventId": 343,
"poapEventFancyId": "gitpoap-gitpoap-docs-level-2-contributor-2022",
"name": "GitPOAP: gitpoap-docs Level 2 Contributor 2022",
"year": 2022,
"description": "You've made at least 5 contributions to the gitpoap-docs project in 2022!",
"imageUrl": "https://assets.poap.xyz/gitpoap-2022-devconnect-hackathon-gitpoap-team-contributor-2022-logo-1650466033470.png",
"repositories": ["gitpoap/gitpoap-docs"],
"mintedCount": 5,
}]
"gitPoapEvents": [
{
"gitPoapEventId": 32423,
"poapEventId": 343,
"poapEventFancyId": "gitpoap-gitpoap-docs-level-2-contributor-2022",
"name": "GitPOAP: gitpoap-docs Level 2 Contributor 2022",
"year": 2022,
"description": "You've made at least 5 contributions to the gitpoap-docs project in 2022!",
"imageUrl": "https://assets.poap.xyz/gitpoap-2022-devconnect-hackathon-gitpoap-team-contributor-2022-logo-1650466033470.png",
"repositories": ["gitpoap/gitpoap-docs"],
"mintedCount": 5
}
]
}
```

<br />

### `GET /v1/gitpoaps/:gitPoapEventId/addresses`
</div>
</details>

This endpoint allows users to query for a list of addresses that hold a GitPOAP specified by GitPOAP Event ID. It returns something like:
<details>
<summary>
<h3>Query for a list of addresses that hold a GitPOAP by GitPOAP EventID</h3>
<code>GET /v1/gitpoaps/:gitPoapEventId/addresses</code>
</summary>
<div>
This endpoint allows users to query for a list of addresses that hold a GitPOAP specified by GitPOAP Event ID. It returns something like:

```json
{
Expand All @@ -163,11 +196,16 @@ And in the case that no GitPOAP with that ID is found, it returns the following
}
```

<br />
</div>
</details>

### `GET /v1/gitpoaps/addresses`

This endpoint allows users to query for a list of all addresses that hold any GitPOAP. It returns something like:
<details>
<summary>
<h3>Query for a list of all addresses that hold any GitPOAP</h3>
<code>GET /v1/gitpoaps/addresses</code>
</summary>
<div>
This endpoint allows users to query for a list of all addresses that hold any GitPOAP. It returns something like:

```json
{
Expand All @@ -180,11 +218,16 @@ This endpoint allows users to query for a list of all addresses that hold any Gi
}
```

<br />
</div>
</details>

### `GET /v1/address/:address/gitpoaps`

This endpoint allows users to query for some address's (either an ETH or ENS address) GitPOAPs. This returns data like:
<details>
<summary>
<h3>Query for GitPOAPs belonging to an Ethereum address</h3>
<code>GET /v1/address/:address/gitpoaps</code>
</summary>
<div>
This endpoint allows users to query for some address's (either and ETH or ENS address) GitPOAPs. This returns data like:

```json
[
Expand All @@ -205,12 +248,17 @@ This endpoint allows users to query for some address's (either an ETH or ENS add
]
```

<br />

### `GET /v1/github/user/:githubHandle/gitpoaps?status=<status>`
</div>
</details>

This endpoint allows users to query for minted GitPOAPs associated with a specified GitHub handle. The `status` query parameter is one of
the following: `claimed`, `unclaimed`, `pending`, `minting`, and can be omitted completely. This returns data like:
<details>
<summary>
<h3>Query for GitPOAPs associated with a Github handle</h3>
<code>GET /v1/github/user/:githubHandle/gitpoaps?status=[status]</code>
</summary>
<div>
This endpoint allows users to query for minted GitPOAPs associated with a specified GitHub handle. The `status` query parameter is one of
the following: `claimed`, `unclaimed`, `pending`, `minting`, and can be ommitted completely. This returns data like:

```json
[
Expand All @@ -231,18 +279,37 @@ the following: `claimed`, `unclaimed`, `pending`, `minting`, and can be omitted
]
```

<br />
</div>
</details>

### `GET /v1/repo/:owner/:name/badge`
### Badge

<details>
<summary>
<h3>Add a GitPOAP badge to the README.md</h3>
<code>GET /v1/repo/:owner/:name/badge</code><br />
</summary>
<div>

This endpoint generates a GitHub badge containing the count of minted GitPOAPs for a specified repo. The repo is specified with a GitHub owner and repo name & the endpoint will return a SVG for use in any `.md` file such as a `README.md`.

Using `ethereum/ethereum-org-website` as an example via [https://public-api.gitpoap.io/v1/repo/ethereum/ethereum-org-website/badge](https://public-api.gitpoap.io/v1/repo/ethereum/ethereum-org-website/badge), embed the badge in a `.md` file the following way:
API link: `https://public-api.gitpoap.io/v1/repo/[your organization]/[your repo]/badge`

```markdown
[![GitPOAP Badge](https://public-api.gitpoap.io/v1/repo/gitpoap/gitpoap-docs/badge)](https://www.gitpoap.io/gh/gitpoap/gitpoap-docs)
```
The badge is embedded in any `.md` file by adding this line:

`[![GitPOAP Badge](https://public-api.gitpoap.io/v1/repo/[your organization]/[your repo]/badge)](https://www.gitpoap.io/gh/[your organization]/[your repo])`

Using `github.com/ethereum/ethereum-org-website` as an example: <br/>
`[!GitPOAP Badge](https://public-api.gitpoap.io/v1/repo/ethereum/ethereum-org-website/badge)](https://www.gitpoap.io/gh/ethereum/ethereum-org-website)`

An example of how it looks after embedding can be found [here](./badge#example)

Resulting in the following:
</div>
</details>

<br />

---

[![GitPOAP Badge](https://public-api.gitpoap.io/v1/repo/gitpoap/gitpoap-docs/badge)](https://www.gitpoap.io/gh/gitpoap/gitpoap-docs)
Questions about the GitPOAP API and its uses can be directed at the #support channel in the [GitPOAP
Discord](https://www.gitpoap.io/discord)
37 changes: 37 additions & 0 deletions docs/badge.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
id: badge
title: GitHub badge
sidebar_position: 5
---

:::tip

Click here to skip to the [Quickstart Badge Embed Instructions](./api/#badge).

:::

## Display Github badge on your README.md

Use the GitPOAP API to display the number of GitPOAPs that have been minted in your eligible repo. This will signal to potential contributors know that your repo is GitPOAP-eligible.

### Example

Ethereum’s [ethereum/ethereum-org-website](https://github.com/ethereum/ethereum-org-website) Github repo

<ImageContainer>
<img
src={require('@site/static/img/gitpoap_visuals/ethereumorgbadge.png').default}
style={{
maxWidth: '100%',
textAlign: 'right',
}}
/>
</ImageContainer>
<br />
<br />

:::tip

Click here to skip to the [Quickstart Badge Embed Instructions](./api/#badge).

:::
33 changes: 33 additions & 0 deletions docs/community-calls.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
id: community-calls
title: Community Calls
sidebar_position: 5
---

### What’s the purpose of the community calls?

GitPOAP wants to support open source projects - that means giving projects the tools to reward their contributors and also connecting potential new contributors to projects actively seeking them.

**We want contributors to feel like they have an entry point to contribute to these projects**. The audience will get to know the maintainer and the project - we’ll help get context for what it does, how it works, and specifically what they’re seeking contributions on.

### What do the calls look like?

POAP generously hosts our community call livestreams on [the POAP youtube channel](https://www.youtube.com/channel/UCvXWjomx55gbEjJ3PCPPezQ/streams). They are also published as podcasts and are available with your favorite podcast app. Will there be a POAP? Always!

Calls generally go something like:

- GitPOAP intro and updates
- Guest intro
- Project overview
- How can contributors get involved?

Chatter during the call happens in the [GitPOAP’s discord](https://www.gitpoap.io/discord) #general channel.

### Previous community calls

1. [Community Call #1](https://www.youtube.com/watch?v=YYtCNfa2oxs): [Paul Wackerow](https://twitter.com/wackerow), EF, and [ethereum.org](http://ethereum.org/) maintainer
2. [Community Call #2](https://www.youtube.com/watch?v=NHKeB2RAoBA): [Ryan Berckmans](https://twitter.com/ryanberckmans), who’s [researching web3 e-commerce](https://github.com/ryanberckmans/3cities-open)
3. [Community Call #3](https://www.youtube.com/watch?v=vEQMV0SXpMQ): [Alex Stokes](https://twitter.com/ralexstokes), EF, researching MEV and [building mev-rs](https://github.com/ralexstokes/mev-rs)
4. [Community Call #4](https://www.youtube.com/watch?v=XhmZUXsL3Zk): [Zainan Victor Zhou](https://github.com/xinbenlv), EIP Editor and [building ERCRef](https://github.com/ercref/)
5. [Community Call #5](https://www.youtube.com/watch?v=1nDiBBK43Ak): [Manfred Touron](https://github.com/moul), building [Berty](https://github.com/berty)
6. [Community Call #6](https://www.youtube.com/watch?v=SKbczOTKckQ): [Ivan Kalyaev](https://github.com/katspaugh) of wavesurfer.js and [Safe](https://github.com/safe-global)
Loading