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

feat: add API documentation following OpenAPI standard #13

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
Open

feat: add API documentation following OpenAPI standard #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
225e592
fix: update drand cli to v2
kenyiu Feb 20, 2025
3ad5242
Merge branch 'drand:master' into master
kenyiu Feb 20, 2025
7d7f88c
chore: upgrade Docusaurus packages to 3.7
kenyiu Mar 1, 2025
5ae89bc
feat: add API documentation following OpenAPI standard
kenyiu Mar 1, 2025
cafaad7
docs: update OpenAPI documentation and configuration
kenyiu Mar 9, 2025
b1e447b
Merge branch 'master' into feat/add-API-documentation-following-OpenA…
kenyiu Mar 9, 2025
b645181
feat: added v2 api based on http-relay repo
kenyiu Mar 16, 2025
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
8 changes: 8 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,14 @@ $ yarn start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

#### Updating the api yaml file

After updating the `drand-api.yaml` file, you need to run the following command to update the api docs:

```
yarn docusaurus gen-api-docs all
```

### Build

```
Expand Down
79 changes: 1 addition & 78 deletions docs/03_dev-guide/03-04-HTTP_API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,81 +56,4 @@ As you can see, they are currently running various chains as explained below. We

Other testnet chains, such as our first "unchained" testnet (`7672797f548f3f4748ac4bf3352fc6c6b6468c9ad40ad456a397545c6e2df5bf`) or our first G1 based non-RFC compliant chain (`f3827d772c155f95a9fda8901ddd59591a082df5ac6efe3a479ddb1f5eeb202c`) may be deprecated in the future.

## **`/chains`**

Retrieves the *chain hash* of every running network a user can interact with. It returns a JSON object with the following structure:

```jsx
[
"8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce",
"859504eade86790ad09b2b3474d5e09d1718b549ef7107d7bbd18f5e221765ce",
"8252d7db02664c1f6b20f40c6e8e138704d2acfeb6c5abcc14c77e3a842b2f84",
"515e7366248ca37b1460d23b4f98493c246fbb02851f2a43a710c968a349f8d6"
]
```

## **`/{chain-hash}/info`**

Retrieves the randomness chain information. It returns a JSON object with the following structure:

```jsx
{
"public_key": "868f005eb8e6e4ca0a47c8a77ceaa5309a47978a7c71bc5cce96366b5d7a569937c529eeda66c7293784a9402801af31",
"period": 30,
"genesis_time": 1595431050,
"hash": "8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce",
"groupHash": "176f93498eac9ca337150b46d21dd58673ea4e3581185f869672e59fa4cb390a",
"schemeID": "pedersen-bls-chained",
"metadata": {
"beaconID": "default"
}
}
```

- `public_key` is the distributed public key of the drand group
- `period` is the time in seconds between randomness beacon rounds
- `genesis_time` is the time in seconds since the Unix Epoch that the group began generating randomness
- `hash` is the *chain hash*, which uniquely identifies the drand chain. It is used as a root of trust for validation of the first round of randomness.
- `groupHash` is the hash of a file containing the current set of nodes participating in the network. The group file is updated on every resharing.
- `schemeID` is the name of the scheme this network uses. The scheme specifies the type of cryptography being used to generate the randomness beacons.
- `metadata` contains some miscellaneous metadata about the network that is added to most packets during operation.

## **`/{chain-hash}/public/latest`**

Retrieves the latest round of randomness. It returns a JSON object with the following structure:

```jsx
{
"round": 367,
"randomness": "3439d92d58e47d342131d446a3abe264396dd264717897af30525c98408c834f",
"signature": "90957ebc0719f8bfb67640aff8ca219bf9f2c5240e60a8711c968d93370d38f87b38ed234a8c63863eb81f234efce55b047478848c0de025527b3d3476dfe860632c1b799550de50a6b9540463e9fb66c8016b89c04a9f52dabdc988e69463c1",
"previous_signature": "859504eade86790ad09b2b3474d5e09d1718b549ef7107d7bbd18f5e221765ce8252d7db02664c1f6b20f40c6e8e138704d2acfeb6c5abcc14c77e3a842b2f84515e7366248ca37b1460d23b4f98493c246fbb02851f2a43a710c968a349f8d6"
}
```

- `round` is a monotonically increasing integer - the randomness round index
- `randomness` is a SHA-256 hash of the signature
- `signature` is the *Boneh-Lynn-Shacham* (BLS) signature for this round of randomness
- `previous_signature` is the signature of the previous round of randomness

## **`/{chain-hash}/public/{round}`**

Retrieves a previous round of randomness identified by the positive integer `round`. Note that specifying `0` will retrieve the latest round. It returns a JSON object with the following structure:

```jsx
{
"round": 367,
"randomness": "3439d92d58e47d342131d446a3abe264396dd264717897af30525c98408c834f",
"signature": "90957ebc0719f8bfb67640aff8ca219bf9f2c5240e60a8711c968d93370d38f87b38ed234a8c63863eb81f234efce55b047478848c0de025527b3d3476dfe860632c1b799550de50a6b9540463e9fb66c8016b89c04a9f52dabdc988e69463c1",
"previous_signature": "859504eade86790ad09b2b3474d5e09d1718b549ef7107d7bbd18f5e221765ce8252d7db02664c1f6b20f40c6e8e138704d2acfeb6c5abcc14c77e3a842b2f84515e7366248ca37b1460d23b4f98493c246fbb02851f2a43a710c968a349f8d6"
}
```

- `round` is a sequentially increasing integer - the randomness round index
- `randomness` is a SHA-256 hash of the signature
- `signature` is the *Boneh-Lynn-Shacham* (BLS) signature for this round of randomness
- `previous_signature` is the signature of the previous round of randomness (note: this will is omitted for [**unchained networks**](../concepts/2-1-concepts-cryptography#%EF%B8%8F-chained-and-unchained-modes)

**Note**: For backwards-compatibility reasons, paths without `chain-hash` will resort to the the default network in operation.

---
For details of the API Documentation, please refer to the [API Documentation](/docs/dev-guide/3.7%20API%20Documentation/drand-http-api).
71 changes: 71 additions & 0 deletions docs/03_dev-guide/3.7 API Documentation v1/chain-hash-info.api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
---
id: chain-hash-info
title: "/:chain-hash/info"
description: "Retrieves metadata about a specific randomness chain, identified by its chain hash."
sidebar_label: "/:chain-hash/info"
hide_title: true
hide_table_of_contents: true
api: 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what is this large base64 blob?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are metadata for the API generated by the docusaurus-plugin-openapi-docs package from the yaml files. (yarn docusaurus clean-api-docs all && yarn docusaurus gen-api-docs all)

The string will be used here afterwards:
https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/e4d3ec4ebfb8415e97951076ce2f0901e8d88168/packages/docusaurus-theme-openapi-docs/src/theme/ApiItem/index.tsx#L78

I have wrote a quick script for you to check what's stored in the blob.

const pako = require('pako');

function base64ToUint8Array(base64) {
  const binary = atob(base64);
  const len = binary.length;
  const bytes = new Uint8Array(len);
  for (let i = 0; i < len; i++) {
    bytes[i] = binary.charCodeAt(i);
  }
  return bytes;
}
let api = "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";
apiJson = JSON.parse(
  new TextDecoder().decode(pako.ungzip(base64ToUint8Array(api)))
);
console.log(apiJson);

The output would be:

{
  description: 'Retrieves metadata about a specific randomness chain, identified by its chain hash.',
  parameters: [
    {
      name: 'chain-hash',
      in: 'path',
      required: true,
      schema: [Object],
      example: '8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce',
      description: 'The hexadecimal hash identifying the chain (e.g., default chained network).'
    }
  ],
  responses: {
    '200': { description: 'Chain information\n', content: [Object] },
    '404': { description: 'Chain not found', content: [Object] }
  },
  method: 'get',
  path: '/{chain-hash}/info',
  servers: [
    {
      url: 'https://drand.cloudflare.com',
      description: 'Cloudflare - Public endpoint for the League of Entropy mainnet'
    },
    {
      url: 'https://api.drand.secureweb3.com:6875',
      description: 'Storswift - Public endpoint for the League of Entropy mainnet'
    },
    {
      url: 'https://pl-us.testnet.drand.sh',
      description: 'Protocol Labs - US-based testnet endpoint'
    },
    {
      url: 'https://pl-eu.testnet.drand.sh',
      description: 'Protocol Labs - EU-based testnet endpoint'
    },
    {
      url: 'https://testnet-api.drand.cloudflare.com',
      description: 'Cloudflare - Testnet endpoint'
    }
  ],
  info: {
    title: 'drand HTTP API',
    description: 'Drand provides a JSON HTTP interface that clients can use to fetch randomness from each drand network running on nodes.\n' +
      "If you're using drand in an application, it may be easier and more secure to use one of the client libraries, \n" +
      'which will also perform verification of randomness rounds and add additional features like failover, racing, aggregation, \n' +
      'and caching.\n' +
      '\n' +
      "All that's required is the address of the HTTP interface and way to fetch from HTTP, e.g. curl.\n" +
      '\n' +
      'The version 1 of public [League of Entropy](https://blog.cloudflare.com/league-of-entropy/) HTTP APIs are available at:\n' +
      '- Cloudflare\n' +
      '  - https://drand.cloudflare.com\n' +
      '- Storswift\n' +
      '  - https://api.drand.secureweb3.com:6875\n' +
      '\n' +
      'The League of Entropy currently runs two networks in mainnet: default and fastnet. \n' +
      'They are chained and unchained networks respectively, the details of which can be found in the [cryptography \n' +
      'specification](https://drand.love/docs/cryptography/#randomness).\n' +
      '\n' +
      'The chain hash for the League of Entropy default chain running at a 30s frequency in chained mode on Mainnet is:\n' +
      '`8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce`\n' +
      '\n' +
      'It also available at the default context, i.e. omitting the `/{chain-hash}` in the API specification below.\n' +
      '\n' +
      'The chain hash for the League of Entropy quicknet network running at a 3s frequency in unchained mode on Mainnet is:\n' +
      '`52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971`\n' +
      '\n' +
      'Note that [the fastnet network has been deprecated..](https://drand.love/blog/2023/07/03/fastnet-sunset-quicknet-new/)\n' +
      '\n' +
      'Furthermore, we have "testnet endpoints" which are a completely separate environment for testing our latest changes, \n' +
      'potentially helping you detect breaking changes or issues with our latest release before they hit mainnet. \n' +
      'We recommend running your CI/CD against our testnet endpoints as well as our mainnet ones, in order to detect issues early.\n' +
      '\n' +
      'We currently have 3 testnet HTTP(S) endpoints being run by:\n' +
      '\n' +
      '- Protocol Labs\n' +
      '  - https://pl-us.testnet.drand.sh\n' +
      '  - https://pl-eu.testnet.drand.sh\n' +
      '- Cloudflare\n' +
      '  - https://testnet-api.drand.cloudflare.com\n' +
      '\n' +
      'As you can see, they are currently running various chains as explained below. \n' +
      'We are committed to maintaining the default, G2 based, chained testnet chain \n' +
      '(`84b2234fb34e835dccd048255d7ad3194b81af7d978c3bf157e3469592ae4e02`) as well as \n' +
      'the faster, G1 based, unchained quicknet-t testnet chain \n' +
      '(`cc9c398442737cbd141526600919edd69f1d6f9b4adb67e4d912fbc64341a9a5`) \n' +
      'as long as we run the equivalent mainnet networks.\n' +
      '\n' +
      'Other testnet chains, such as our first "unchained" testnet \n' +
      '(`7672797f548f3f4748ac4bf3352fc6c6b6468c9ad40ad456a397545c6e2df5bf`) or our first G1 based non-RFC compliant chain\n' +
      '(f3827d772c155f95a9fda8901ddd59591a082df5ac6efe3a479ddb1f5eeb202c) may be deprecated in the future. \n',
    version: '1.0.0',
    contact: { name: 'drand Team', url: 'https://drand.love/' },
    license: {
      name: 'Apache 2.0 or MIT',
      url: 'https://github.com/drand/drand/blob/main/LICENSE'
    }
  },
  postman: {
    name: '/:chain-hash/info',
    description: {
      content: 'Retrieves metadata about a specific randomness chain, identified by its chain hash.',
      type: 'text/plain'
    },
    url: { path: [Array], host: [Array], query: [], variable: [Array] },
    header: [ [Object] ],
    method: 'GET'
  }
}

sidebar_class_name: "get api-method"
info_path: docs/03_dev-guide/3.7 API Documentation v1/drand-http-api
custom_edit_url: null
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
as={"h1"}
className={"openapi__heading"}
children={"/:chain-hash/info"}
>
</Heading>

<MethodEndpoint
method={"get"}
path={"/{chain-hash}/info"}
context={"endpoint"}
>

</MethodEndpoint>



Retrieves metadata about a specific randomness chain, identified by its chain hash.

<Heading
id={"request"}
as={"h2"}
className={"openapi-tabs__heading"}
children={"Request"}
>
</Heading>

<ParamsDetails
parameters={[{"name":"chain-hash","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"example":"8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce","description":"The hexadecimal hash identifying the chain (e.g., default chained network)."}]}
>

</ParamsDetails>

<RequestSchema
title={"Body"}
body={undefined}
>

</RequestSchema>

<StatusCodes
id={undefined}
label={undefined}
responses={{"200":{"description":"Chain information\n","content":{"application/json":{"schema":{"type":"object","properties":{"public_key":{"type":"string","description":"The distributed public key of the drand group","example":"868f005eb8e6e4ca0a47c8a77ceaa5309a47978a7c71bc5cce96366b5d7a569937c529eeda66c7293784a9402801af31"},"period":{"type":"integer","description":"The time in seconds between randomness beacon rounds","example":30},"genesis_time":{"type":"integer","description":"The time in seconds since the Unix Epoch that the group began generating randomness","example":1595431050},"hash":{"type":"string","description":"The chain hash, which uniquely identifies the drand chain. It is used as a root of trust for validation of the first round of randomness.","example":"8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce"},"groupHash":{"type":"string","description":"The hash of a file containing the current set of nodes participating in the network. The group file is updated on every resharing","example":"176f93498eac9ca337150b46d21dd58673ea4e3581185f869672e59fa4cb390a"},"schemeID":{"type":"string","description":"The name of the scheme this network uses. The scheme specifies the type of cryptography being used to generate the randomness beacons","example":"pedersen-bls-chained"},"metadata":{"type":"object","properties":{"beaconID":{"type":"string","description":"The identifier for the beacon.","example":"default"}},"description":"Contains some miscellaneous metadata about the network that is added to most packets during operation"}},"required":["public_key","period","genesis_time","hash","groupHash","schemeID","metadata"],"title":"ChainInfo"},"example":{"public_key":"868f005eb8e6e4ca0a47c8a77ceaa5309a47978a7c71bc5cce96366b5d7a569937c529eeda66c7293784a9402801af31","period":30,"genesis_time":1595431050,"hash":"8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce","groupHash":"176f93498eac9ca337150b46d21dd58673ea4e3581185f869672e59fa4cb390a","schemeID":"pedersen-bls-chained","metadata":{"beaconID":"default"}}}}},"404":{"description":"Chain not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"chain not found"}}}}}}}}
>

</StatusCodes>



71 changes: 71 additions & 0 deletions docs/03_dev-guide/3.7 API Documentation v1/chain-hash-public-latest.api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
---
id: chain-hash-public-latest
title: "/:chain-hash/public/latest"
description: "Retrieves the most recent randomness value from the default chain. Note this might not be available on all chained networks; prefer using chain-specific endpoints or relays for consistency."
sidebar_label: "/:chain-hash/public/latest"
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "get api-method"
info_path: docs/03_dev-guide/3.7 API Documentation v1/drand-http-api
custom_edit_url: null
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
as={"h1"}
className={"openapi__heading"}
children={"/:chain-hash/public/latest"}
>
</Heading>

<MethodEndpoint
method={"get"}
path={"/{chain-hash}/public/latest"}
context={"endpoint"}
>

</MethodEndpoint>



Retrieves the most recent randomness value from the default chain. Note this might not be available on all chained networks; prefer using chain-specific endpoints or relays for consistency.

<Heading
id={"request"}
as={"h2"}
className={"openapi-tabs__heading"}
children={"Request"}
>
</Heading>

<ParamsDetails
parameters={[{"name":"chain-hash","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"example":"52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971"}]}
>

</ParamsDetails>

<RequestSchema
title={"Body"}
body={undefined}
>

</RequestSchema>

<StatusCodes
id={undefined}
label={undefined}
responses={{"200":{"description":"Randomness data for the latest round\n","content":{"application/json":{"schema":{"type":"object","properties":{"round":{"type":"integer","description":"A monotonically increasing integer - the randomness round index","example":367},"randomness":{"type":"string","description":"A SHA-256 hash of the signature","example":"3439d92d58e47d342131d446a3abe264396dd264717897af30525c98408c834f"},"signature":{"type":"string","description":"The Boneh-Lynn-Shacham (BLS) signature for this round of randomness","example":"90957ebc0719f8bfb67640aff8ca219bf9f2c5240e60a8711c968d93370d38f87b38ed234a8c63863eb81f234efce55b047478848c0de025527b3d3476dfe860632c1b799550de50a6b9540463e9fb66c8016b89c04a9f52dabdc988e69463c1"},"previous_signature":{"type":"string","description":"The signature of the previous round of randomness (this will is omitted for unchained networks)","example":"859504eade86790ad09b2b3474d5e09d1718b549ef7107d7bbd18f5e221765ce8252d7db02664c1f6b20f40c6e8e138704d2acfeb6c5abcc14c77e3a842b2f84515e7366248ca37b1460d23b4f98493c246fbb02851f2a43a710c968a349f8d6"}},"required":["round","randomness","signature"],"title":"Randomness"}}}},"503":{"description":"Latest randomness unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"latest randomness not available"}}}}}}}}
>

</StatusCodes>



Loading