Skip to content

Commit

Permalink
add wording around service endpoint being a base URL
Browse files Browse the repository at this point in the history
  • Loading branch information
@jiyoonie9
jiyoonie9 committed Aug 15, 2024
1 parent 2415831 commit 766aba6
Showing 1 changed file with 37 additions and 33 deletions.
70 changes: 37 additions & 33 deletions specs/http-api/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,26 +70,30 @@ Version: Draft
# Discoverability
PFIs can become publicly discoverable by advertising their API endpoint as a [Service](https://www.w3.org/TR/did-core/#services) within their DID Document. In order to increase the likelihood of being discovered The `service` entry **SHOULD** include the following properties:

| Property | Value |
| ----------------- | ------------------------------------------------------------- |
| `id` | see [DID-CORE spec](https://www.w3.org/TR/did-core/#services) |
| `type` | `PFI` |
| `serviceEndpoint` | PFI's publicly addressable API endpoint |
| Property | Value |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | see [DID-CORE spec](https://www.w3.org/TR/did-core/#services) |
| `type` | `PFI` |
| `serviceEndpoint` | PFI's publicly addressable API endpoint, the [base URL](https://swagger.io/docs/specification/api-host-and-base-path/) with which tbDEX HTTP requests can be made. |

The ID can be chosen at the discretion of the PFI, but the service entry should be of type `PFI`.

## Example
```json
{
"id": "did:example:pfi",
"service": [{
"id":"my-pfi",
"id":"#my-pfi",
"type": "PFI",
"serviceEndpoint": "https://pfi.organization.com"
}]
}
```

This example illustrates that:
* The ID can be chosen at the discretion of the PFI, but the service entry should be of type `PFI`.
* The `serviceEndpoint` of the PFI `https://pfi.organization.com` is the PFI's base URL.
* The PFI's base URL is combined with relative paths listed below (i.e. `POST /exchanges`) by the client to create an tbDEX HTTP request to the PFI.

> [!NOTE]
>
> _Decentralized_ discoverability is dependent upon whether the underlying [verifiable registry](https://www.w3.org/TR/did-core/#dfn-verifiable-data-registry) of the selected [DID Method](https://www.w3.org/TR/did-core/#methods) is crawlable
Expand Down Expand Up @@ -319,10 +323,10 @@ False
```

### Response
| Status | Body |
| ---------------------------- | --------------------- |
| `202: Accepted` | N/A |
| `400: Bad Request` | `{ errors: Error[] }` |
| Status | Body |
| ------------------ | --------------------- |
| `202: Accepted` | N/A |
| `400: Bad Request` | `{ errors: Error[] }` |

### Errors
| Status | Description |
Expand Down Expand Up @@ -355,10 +359,10 @@ False
```

### Response
| Status | Body |
| ---------------------------- | --------------------- |
| `202: Accepted` | N/A |
| `400: Bad Request` | `{ errors: Error[] }` |
| Status | Body |
| ------------------ | --------------------- |
| `202: Accepted` | N/A |
| `400: Bad Request` | `{ errors: Error[] }` |


### Errors
Expand All @@ -383,12 +387,12 @@ True. See [Authentication](#authentication) section for more details.

### Response

| Status | Body |
| ---------------------------- | -------------------------- |
| `200: OK` | `{ data: TbdexMessage[] }` |
| `400: Bad Request` | `{ errors: Error[] }` |
| `401: Unauthorized` | `{ errors: Error[] }` |
| `404: Not Found` | N/A |
| Status | Body |
| ------------------- | -------------------------- |
| `200: OK` | `{ data: TbdexMessage[] }` |
| `400: Bad Request` | `{ errors: Error[] }` |
| `401: Unauthorized` | `{ errors: Error[] }` |
| `404: Not Found` | N/A |

---

Expand All @@ -404,12 +408,12 @@ Returns a list of exchange IDs
True. See [Authentication](#authentication) section for more details.

### Response
| Status | Body |
| ---------------------------- | ---------------------------------------------- |
| `200: OK` | List of exchangeIds, i.e. `{ data: string[] }` |
| `400: Bad Request` | `{ errors: Error[] }` |
| `401: Unauthorized` | `{ errors: Error[] }` |
| `404: Not Found` | N/A |
| Status | Body |
| ------------------- | ---------------------------------------------- |
| `200: OK` | List of exchangeIds, i.e. `{ data: string[] }` |
| `400: Bad Request` | `{ errors: Error[] }` |
| `401: Unauthorized` | `{ errors: Error[] }` |
| `404: Not Found` | N/A |

---

Expand All @@ -426,12 +430,12 @@ True. See [Authentication](#authentication) section for more details.
`GET /balances`

### Response
| Status | Body |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `200: OK` | `{ data: Balance[] }` See [Balance structure](https://github.com/TBD54566975/tbdex/blob/main/specs/protocol/README.md#balance) |
| `400: Bad Request` | `{ errors: Error[] }` |
| `401: Unauthorized` | `{ errors: Error[] }` |
| `404: Not Found` | N/A |
| Status | Body |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `200: OK` | `{ data: Balance[] }` See [Balance structure](https://github.com/TBD54566975/tbdex/blob/main/specs/protocol/README.md#balance) |
| `400: Bad Request` | `{ errors: Error[] }` |
| `401: Unauthorized` | `{ errors: Error[] }` |
| `404: Not Found` | N/A |

# References
* JSON:API spec: https://jsonapi.org/format/

0 comments on commit 766aba6

Please sign in to comment.