API Documentation

[Reckless-Satoshi]

We are using django-rest-framework so it is a very low hanging fruit to exploit the API. In fact, some developers seem to be using it before any documentation has been made. This is due to how simple and easy it is to explore the robosats API. Will summarize here everything you need to know to use it.

Short API documentation

Simply open your Tor Browser (http://robosats6tkf3eva7x2voqso3a5wcorsnw34jveyxfqi2fu7oyheasid.onion) and check the following endpoints for full details:

Order limits for every currency pair

/api/limits/

Historical exchange activity

/api/historical/

All Market Ticks

/api/ticks/

General exchange information

/api/info/

Exchange rates and premiums

/api/price/

For all national currencies for non-KYC BTC in the RoboSats market (this data has some limitations)

Every public order in the book

/api/book/?currency=0&type=2

Use the currency number to query only public orders for one currency, use 0 for all. Types, use 0 for BUY orders, 1 for SELL orders, 2 for ALL.

New user or login

/api/user/?token=

Create a new user or login if there is an existing user. Token should satisfy minimum entropy constrains

Make an order

/api/make/

Orders

/api/order/?order_id=

Check order information. Use the POST method for updating the order. By updating the order when needed, a complete trade pipeline can be completed just by using this endpoint.

---

The only thing that is not accessible trough those endpoints is the chatrooms.

[zx9r]

Fixing incorrect link for currency numbers file:

https://github.com/Reckless-Satoshi/robosats/blob/main/frontend/static/assets/currencies.json

[ShatteredBunny]

What about adding Swagger/OpenAPI for documentation? Main benefits:

• Frontend code could be generated including types
• E.g. SwaggerUI would provide an up to date and interactive documentation

[Reckless-Satoshi]

Swagger/OpenAPI for documentation?

I have no experience myself with these and what are the benefits over plain Django Restframework. I've done a little research and looks like a good idea. Maybe the best tool for this is drf-yasg ? It looks straightforward, what do you think? We could create a rewarded task for it.

[ShatteredBunny]

I've also done a little research, django seems to be able to generate OpenAPI schemas, maybe that is good enough: https://www.django-rest-framework.org/topics/documenting-your-api/
So we could just add SwaggerUI to replace this issue (code as documentation, no need to update docs manually)

As mentioned in the drf-yasg readme, drf-spectacular uses OpenAPI 3.0 instead of 2.0 and is also actively maintained, I think this would be the best choice if we want something more powerful
drf-spectacular would allow to add annotations describing the endpoint (description, query parameters, optional or required etc.), I don't know if this is possible with plain django restframework.
The goal is that code for API calls could be generated including all parameters and types, e.g. using openapi-generator-cli and axios HTTP client
So the API cannot be used in a wrong way by accident, type errors in the frontend when the api changed (after converting components to ts) etc.

[Reckless-Satoshi]

Would you make short bullet-point list of what this task might look like? Just to get a rough idea how much work implementing this would be.

I believe it is not as high priority as other rewarded tasks, but we could only put into it 100K to 200K Sats as a bit of an incentive.

[ShatteredBunny]

I believe it is not as high priority as other rewarded tasks

Agreed, it's only for convenient development

Possible steps for this task:

Backend

• Expose OpenAPI definition endpoint (JSON). If it is possible to do everything using Django restframework, that's best; otherwise e.g. drf-spectacular could be used
• Add UI replacing this issue, e.g. SwaggerUI
• Make sure the API definition is complete, in particular that all request and response types and parameters are available and correct. If possible this is auto-generated, but maybe metadata in form of annotations is necessary. Also add the descriptions from this issue

Frontend

• Generate TypeScript code from OpenAPI definition endpoint and document how to do it
• Refactor frontend code to use generated code

[Reckless-Satoshi]

I see all of these points are quite a bit of work. However, the generation of TypeScript code for the frontend and refactoring puts us one step closer to following best practices and can be seen as a prerequisite towards RoboSats PRO frontend.

Documenting the API task as defined by @ShatteredBunny above is ⚡ rewarded with 300K Sats ⚡ Send a comment if you want to be assigned.

[redphix]

Hey I want to take a dig at this! One question though.

Generate TypeScript code from OpenAPI definition endpoint and document how to do it

Does this mean automatically fetching all routes and auto defining handlers/functions? Also auto defining TS models for request/response schemas?

[redphix]

Or I feel like we can use a client-library generator (there are a few of them available) that would create a library from the openapi spec. Maybe this could be incorporated in the build pipeline? @Reckless-Satoshi. That could be a bit of a stretch I guess, but need to see how viable and useful that would be.

[ShatteredBunny]

Generate TypeScript code from OpenAPI definition endpoint and document how to do it

Does this mean automatically fetching all routes and auto defining handlers/functions? Also auto defining TS models for request/response schemas?

My idea was that you start the backend with openapi endpoint and then run the generation command which fetches the definition and generates the code

I already played a bit around, you can have a look at my fork, branch api-docs. In the package.json is a generation command. Code is generated and I tested usage with the stealth invoice endpoint. The definitions are incomplete though and I don't know what best practices in python/django are...

[ShatteredBunny]

create a library from the openapi spec

I'd like it but then it belongs into another repository?

[redphix]

I'd like it but then it belongs into another repository?

Yes. Was thinking the same, but do we want it is the question? Definitely makes it easier for people writing their own frontends bots to quickly use the library. Thoughts @Reckless-Satoshi ?

edit: on second thoughts though, it seems a little overkill. A REST api with proper openapi spec seems to be more than enough.

[redphix]

I already played a bit around, you can have a look at my fork, branch api-docs. In the package.json is a generation command. Code is generated and I tested usage with the stealth invoice endpoint. The definitions are incomplete though and I don't know what best practices in python/django are...

Nice! There should be a way to get the yaml without running the backend I guess right? After all it's all static, so it should be plausible(?)

[ShatteredBunny]

Nice! There should be a way to get the yaml without running the backend I guess right? After all it's all static, so it should be plausible(?)

Theoretically, not sure. But is this necessary? Once in production one can also get the yaml from there

[ShatteredBunny]

edit: on second thoughts though, it seems a little overkill. A REST api with proper openapi spec seems to be more than enough.

Agreed, and it's only ts, useless for other programming languages

[redphix]

But is this necessary? Once in production one can also get the yaml from there

Yes. you don't want to depend on production which is an external source. Say you were developing a new feature that made you change some endpoints or add new endpoints, that certainly won't be available on production. Idk, the extra step of "run the django server before running 'generate-api'" seems to be a little "coupled". We should make it such that we can build the frontend in a static way. i.e everything required to build it is available as a file somewhere. But maybe that's not possible to do statically, and there will be this intermediary step every time - in which case It's just a pipe dream I am having :P

[redphix]

Btw, @ShatteredBunny, don't want to nab this issue from you. If you have already started and were planning to do this anyway, you can take this up :)

[ShatteredBunny]

Yes. you don't want to depend on production which is an external source. Say you were developing a new feature that made you change some endpoints or add new endpoints, that certainly won't be available on production

If you're changing the API you must run it anyway to test it, if you're developing another client, production would be fine
I don't see a great benefit but if you can find something, why not

[ShatteredBunny]

Btw, @ShatteredBunny, don't want to nab this issue from you. If you have already started and were planning to do this anyway, you can take this up :)

Feel free to do it, I intentionally did not get me assigned :)