💡 How can we advertise the Open Syndicate API endpoints?

[JFWooten4]

Right now, the only way to know what services are provided by the API server is to look through the TAD3 code. You have to check where it calls internal and external functions through manual parsing review. This is not compatible with cross-agent collaboration, and so how about we document all the dozens of functions?

[JFWooten4]

This was discussed yesterday after @apes-on-parade walked @tehchives and @JamesAlfonse through the last touches on setting up @WhyDRS's Google Cloud IAM controls. James and Truth helped me walk through orally explaining the endpoint configurations and function permissions.

IAM Authorizers

Longer term - function specifications

This was a big item I wanted to get set up, as cited. And it's why I appreciated that some of the IAM settings came up in the DUNA chat this week.

For clarity, these APIs are all through AWS, and I think it makes sense to use different cloud providers for WhyDRS and the Syndicate. Seems to set very clear boundaries of access control and working efforts.

Here's an example of a functional authorizer, which lets one of the Lambda API Python scripts call a table like investor information. James raised PII concerns over releasing technical reference URLs, and I want to explore this because we chatted about how publication can help anyone contribute new features.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ExamplePolicy",
      "Effect": "Allow",
      "Action": "dynamodb:GetItem",
      "Resource": "arn:aws:dynamodb:us-east-2:123456789012:table/example-table"
    }
  ]
}

Relevant - calling user requirements

Firstly, I have two of the Gateways set up as HTTP methods for maximum efficiency. The first one is api.blocktransfer.com and has the majority of use in the codebases.

Accordingly, there's just a one-step credential verification for short-lived user local environment keys. User here meaning someone with access to the AWS instance just like how we set up Chives and James with cloud admin accounts.

You can scope down permissions to 2FA'd individual accounts, but my goal in the discussion channel is really to keep development permissionless. That's not super doable when experimentation requires viewing PII and accessing sensitive credentials.¹

Routes

Generally

Here are the main routes and the point of this issue to document. I don't think there's a standard way to deploy or even codify routes within a repository.

I've been thinking about adding some versioning. You can see how this impacted past developments with the assets/{code}/deprecated paths.

All the endpoints connect to the API lambdas, and most of the functions in that repo are just querying edger data. For the ones that do interact with internal info, like investor names, there are these default IAM authorizers.

Cryptographically

The other functions rely on custom signature authentication. They use this authorizer made before SEP-53 standardization.

The idea here is similar to WalletConnect, where issuer insiders scan a channel link to sign with their keys. Then you have user-level verification to access PII with the same security as stock transfers.

Note

Example of a login interface mockup. I've been thinking about how to word this in issuer agreements to explain the need for two operator devices in lieu of hardware signers.

Footnotes

1. A little outside the scope here, but this was discussed as solvable through sample data. And we did a live demonstration of using returns to debug without internal CloudWatch log access. ↩

[JFWooten4]

I have started getting at this in 3b0317b. The challenge is that it gets at a lot of the core structural decisions housed within the Sphinx project. I have a lot more experience in Docusaurus-style API documentation and example pages, which should help. May move the whole repo too, so it's independent, since it would not use the read-the-docs base pages.💗