# Aptos Node API Changelog

All notable changes to the Aptos Node API will be captured in this file. This changelog is written by hand for now. It adheres to the format set out by [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

**Note**: The Aptos Node API does not follow semantic version while we are in active development. Instead, breaking changes will be announced with each devnet cut. Once we launch our mainnet, the API will follow semantic versioning closely.

## 1.0.1 (2022-08-10)
- Changed snake casing by updating Poem version. For example, `ed_25519_signature` will now be `ed25519_signature`. This behavior matches serde.

## 1.0.0 (2022-08-04)

This is the first major release of v1 of the Aptos Node API. This first changelog is therefore dedicated to changes between v0 and v1. These changes should only be generally relevant to client / SDK developers, if you are a dapp developer, you likely interact with the API via an SDK, in which case the changelog of that SDK will be more useful to you.

Future changelogs will follow the format laid out by [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

### Major items
- The OpenAPI spec is now generated by the server, based on the API it hosts. To briefly summarize how this works, the API is defined as a collection of endpoints. The spec generator consumes this definition and looks at all the types it uses for requests / responses and follows their structure down until it hits primitive types at the leaves. The `paths` section of the spec is generated from the endpoints and the `components` are generated from the types they use.
- To facilitate this, the API now uses [Poem](https://github.com/poem-web/poem) as its web server, not Warp. Poem supports OpenAPI spec generation out of the box, and was generally the most fully featured option.
- Certain responses are slightly different. In general, the API now opts for greater structure where possible. For example, with `ScriptFunctionId`:
  - Before: `function: "0x1::payment_scripts::peer_to_peer_with_metadata`"
  - After:
    ```tsx
    function: {
        module: {
            address: "0x1",
            name: "payment_scripts",
        },
        name: "peer_to_peer_with_metadata",
    }
    ```
- CI changes have landed that make it impossible to make changes to the API without regenerating the spec and the clients accordingly. This ensures that for a given commit, the API, spec, client, and examples will all be compatible.
- The API is now versioned. `v0` still lives at `/` for now, while `v1` lives at `/v1`.

### Details
This section is dedicated to the finer details of the API change, but we include them here as they may be relevant to client / SDK developers.

- Both APIs are still present and functional. The code has been split where necessary into v0 and v1 subdirectories. This is mostly only the case for the endpoint handlers, the types didn't need to be split. Additional functions have been added to certain shared types, like the Context. The tests and goldenfiles have been split. We will delete v0 once we have gone through a standard migration flow (notify, deprecate, return errors, etc).
- `/transactions/signing_message` has been renamed to `/transactions/encode_submission`.
- Every endpoint can accept input encoded as either JSON or BCS.
    - Except for `/encode_submission`, which takes only JSON.
- Every endpoint can return data encoded as either JSON or BCS.
- The fact that the input and output can be BCS is actually stated in the spec now, where each endpoint works with multiple content types (this is supported by OpenAPI 3.0+).
- When returning BCS, currently every endpoint is just returning the BCS version of what the JSON endpoint would return. This doesn't give us much beyond some network bandwidth savings. We are now working on cutting out the move type resolution in the middle and returning data straight from storage where possible.
- The headers that each endpoint can return are explicitly stated in the spec.
- Each endpoint in the spec now accurately states the exact set of response codes it can return.
- In the error case, we return an AptosError, which can now contain a custom error code, more specific than just the HTTP status code.
- Headers, responses, and parameters do not have their own section in the spec, making the spec a bit more verbose than it could be. See https://github.com/poem-web/poem/issues/321 and https://github.com/poem-web/poem/issues/332.
- Per-endpoint logging is now based on path, not operation ID. We want to change this back pending changes in Poem: https://github.com/poem-web/poem/issues/351.
- All types we use via the API must implement a Poem derive, e.g. Object, Enum, etc. This provides the framework with necessary information for the types to self describe in the spec.
- For types with discriminators (allOf, oneOf, anyOf), to deal with the fact that none of our types explicitly state their type, Poem generates intermediate types as part of attaching `type` to them. We are looking at alternatives, because it makes the spec and its usage a bit more verbose: https://github.com/poem-web/poem/issues/329.
- We return BCS data with the `application/x-bcs` content type. The input uses the existing mime types. We should unify them though: https://github.com/aptos-labs/aptos-core/issues/2275.
- `submit_transaction` now actually returns a pending transaction, whereas before it was returning a transaction enum (so the spec matches now).
- `/transactions/{hash_or_version}` is gone, there are now two endpoints, `/transactions/by_hash/{hash}` and `/transactions/by_version/{version}`.
- Epoch is returned as a U64 (the string wrapper), not a u64. The v0 API received this change too, as the previous behavior was inconsistent and potentially incorrect.
- `/transactions/simulate` returns a `UserTransaction` now, not just a `Transaction`. The user can only ever submit a user transaction to this endpoint, so it can only ever return a user transaction.
- All docs in the spec that incorrectly used a 16 byte address have been updated.
- MoveTypes are now returned as structured structs instead of strings. To deal with some types that we don't have proper parsing for, e.g. generic type params, a new “unparseable” variant has been added. This ensures the response from the API can actually be deserialized.
    - MoveValue has received the same treatment, minus the unparseable stuff.
- Some snake casing is different, e.g. ed25519 became ed_25519 (proper snake casing).
- U64 and U128 have been used throughout every endpoint. There were a couple of places in v0 where we should've been using it but weren't, e.g. paging params.
- The `v1` API runs on a separate port (where the OS selects a free port) behind a reverse proxy running within the node. This works fine with our source and docker based deployments. This is only temporary while we host both APIs.
- The version in the spec itself is now derived from the version of the node, which is 0.1.0. We need to find a better way to manage this version and add a CHANGELOG. To be clear, v0 had the same problem, though the version there was written by hand.
- Types related to tokens are no longer part of the API spec. These were never concretely part of the API, just written there by hand. The TS SDK now defines them by hand, but these types seem to fall more into the ABI work that Jijun is doing. We could also look at adding support for including additional types to components section of the spec. That way they match the underlying code at least.

### Noteworthy PRs
- The main original PR. Here you can see a breakdown of why we chose Poem over the alternatives (of which there were few): https://github.com/aptos-labs/aptos-core/pull/1906.
- This PR focuses on response and error handling: https://github.com/aptos-labs/aptos-core/pull/2139
- This PR adds the remaining endpoints and splits up the testing infrastructure: https://github.com/aptos-labs/aptos-core/pull/2156
- This PR adds a standalone binary for spec generation: https://github.com/aptos-labs/aptos-core/pull/2317

## Deprecation notes
- Currently Aptos nodes host both the v0 and v1 APIs. We will remove the v0 API by 2022-09-01. If you're a dapp developer, you should only need to update to a newer version of the SDK you use. If you're an SDK / client developer, please update your SDK / client. Reach out to the Aptos team via [Discord](https://discord.com/invite/zTDYBEud7U) for assistance with this, we will be happy to help.