Skip to content
This repository has been archived by the owner on Jun 15, 2021. It is now read-only.

WIP Produce the simplest-possible getting started guide for the Bisq HTTP API #54

Closed
wants to merge 16 commits into from
Closed

WIP Produce the simplest-possible getting started guide for the Bisq HTTP API #54

Changes from 1 commit
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
95a2f88
Add 'Monitoring Bisq offers with the Bisq HTTP API'
May 11, 2018
e778141
Apply source highlighting
cbeams May 17, 2018
37f2b19
Favor one line per paragraph
cbeams May 17, 2018
70ce251
Remove unnecessary blank lines
cbeams May 17, 2018
7ee80ee
Render literal text with `backticks` where appropriate
cbeams May 17, 2018
ae5b54a
Edit for grammar, style and clarity
cbeams May 17, 2018
24ffd06
Use --appName to avoid collision with default Bisq app
cbeams May 17, 2018
eea7498
Verify the API is up with 'version' endpoint
cbeams May 17, 2018
911f6ca
Apply cbeams comments
May 21, 2018
17a48d1
Add note about appName parameter.
May 23, 2018
d73a565
Cleanup json snippets
May 23, 2018
b73db83
Add JDK and JavaFX to requirements section.
May 23, 2018
10be120
Merge branch 'master' into http-api-monitor
cbeams Jun 29, 2018
7d8e78c
Remove now-global attributes from header
cbeams Jun 29, 2018
7eb1466
Refine text, headings and admonitions
cbeams Jun 29, 2018
56d3185
Implement basic copy edits
Jun 30, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
6 changes: 0 additions & 6 deletions http-api-monitor-offers.adoc
View file
Open in desktop
Expand Up @@ -2,7 +2,6 @@

This guide walks you through the process of creating a bot that monitors available offers and sends email notifications.
Copy link
Member Author

Choose a reason for hiding this comment

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

I'd like to drop the email notifications. It makes sense for a script you'd actually want to run in real life, but here in a "let's build the simplest possible bot that could actually work for the purposes of getting our heads around the Bisq HTTP API" guide, all the stuff around GMail and email libraries and usernames and passwords and the code required to bootstrap it all is just noise and makes the whole thing longer and more complicated than it needs to be. As I walked through this guide myself, I punted when I got to this point; I just didn't want to deal. Because: (a) I never use my GMail account, (b) it's set up for 2FA anyway so a simple username / password won't work, (c) I don't want to set up a test account just for the purposes of this guide that told me it would take 15 minutes and is now in fact going to suck up more of my time than I want it to.

As an alternative, just print interesting offers (i.e. those that match the filter) to the command line whenever they show up, or if for some reason that is not idiomatic, then to a file that the user can tail.



== What you'll build

You'll build a NodeJS based script that connects to Bisq over HTTP API to get offers and market prices and sends email notification in case any interesting offer is found.
Expand All @@ -15,7 +14,6 @@ You'll build a NodeJS based script that connects to Bisq over HTTP API to get of
* gmail account
* Bisq-api source code (and Maven) or Docker

Copy link
Member Author

Choose a reason for hiding this comment

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

  • Right about here we should do an INFO admonition that lets the user know that the Bisq HTTP API is currently incubating, and that this means things may be a bit rough around the edges, that their feedback is extra appreciated, along with pointers about how to provide that feedback. You may just direct them to the "next steps" section at bottom where they can find out more about providing feedback (see my related comment about 'next steps' below).


== Starting the API

There are two alternative ways you can run Bisq HTTP API, either from docker image or from sources.
Expand All @@ -34,7 +32,6 @@ For more hard core developers that want to run from sources:
cd bisq-api
mvn compile exec:java -Dexec.mainClass="io.bisq.api.app.ApiMain"

Copy link
Member Author

Choose a reason for hiding this comment

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

  • Right about here we should do an INFO admonition that explains why they're having to run a separate instance of Bisq to experiment with the HTTP API. It's going to be confusing as hell for users who have a perfectly good Bisq client already up and running locally to spin up a different, unrelated instance, unless they have that explained to them. I'd just explain it very clearly in the context of this being an "incubating" project, and that when the the project comes out of incubation, this functionality will be integrated directly into the official Bisq client you run locally. In the meantime, you need to spin up a separate instance to experiment with (and provide feedback on!) this incubating project.

Copy link

Choose a reason for hiding this comment

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

done


=== Verify if API is running

In both cases the API should be running on port 8080. You can verify that by executing:
Expand All @@ -44,7 +41,6 @@ In both cases the API should be running on port 8080. You can verify that by exe
[NOTE]
API documentation is available at http://localhost:8080/swagger.


== Getting the offers

Open offers are available under following URL http://localhost:8080/api/v1/offers.
Expand Down Expand Up @@ -146,7 +142,6 @@ Let's install some dependencies:

npm install lodash http-as-promised nodemailer


In general our script will look like this:
Copy link
Member Author

Choose a reason for hiding this comment

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

In the sections that follow, I recommend that all source code snippets:

  • get sourced from an actual, e.g. 'bisqmon.js' source file checked into the repository. Or perhaps http-api-monitor-offers.js to align with the naming of this file. We'll probably need to think more about how to structure companion sources along with these docs in a flat namespace, but it doesn't matter much at this point: what does matter is that the code below should get extracted as snippets from real source code that actually works. Asciidoctor has great tools to help here, see https://asciidoctor.org/docs/user-manual/#include-partial.

  • get labeled such that they show the name of the file they're coming from (it's fine if all three are labeled as coming from the same file. The point is that this guide needs to be an extremely literal, step-by-step process of going from zero to working code. So if there is code that the user should write, you should tell them where to write it (i.e. in a file named bisqmon.js) and in which order to write it. Add this statement, add this function, and that function, and you're done.

Copy link

Choose a reason for hiding this comment

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

both done


[source,javascript]
Expand Down Expand Up @@ -216,7 +211,6 @@ function getPriceFilter(marketPrice) {

We are multiplying `marketPrice` by `10000` because that is the format in which the API returns the price.
Copy link
Member Author

Choose a reason for hiding this comment

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

  • Somewhere right about here, you should instruct the user to actually run node bisqmon.js (or whatever the correct invocation should be), and then show them what they should expect to see as correct output. This is the big payoff. They've hung with us for 15 minutes, reading our instructions, taking in the context, and following each step faithfully. Now they get what they came for: working code that does exactly what we said it would.

Copy link

Choose a reason for hiding this comment

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

done



Here is a full script. You must substitute EMAIL_ACCOUNT_USERNAME, EMAIL_ACCOUNT_PASSWORD, EMAIL_FROM_ADDRESS and EMAIL_TO_ADDRESS
with appropriate values.

Expand Down