[API] Document public API

[AlexeySachkov]

I found a few issues where people asking some questions about an existing API trying to setup some integration of their tools with the Homebrewery.

I think we could document API to simplify integration of external tools with the Hombrewery.

See #194, #162

[G-Ambatte]

The API doesn't appear to be restricted at the moment; I was able to create a new brew as an anonymous user by using the following chunk of JS:

test.js

const request = require('superagent');

const res = request.post('https://homebrewery.naturalcrit.com/api')
				.send({ title: "Test Title", text: "# Test Text" })
				.catch((err)=>{
					console.log('Error creating Local Copy');
					this.setState({ errors: err });
					return;
				})
				.then(function(result) {
					console.log(result.body);
					return result;
				});

Running node test.js resulted in the following:

{
  title: 'Test Title',
  description: '',
  tags: '',
  systems: [],
  renderer: '',
  authors: [],
  published: false,
  views: 0,
  version: 1,
  _id: '6104b739fbfbf400179b0915',
  shareId: 'Hdpt5VKlbI1n',
  editId: 'DomQTQp4BtO7',
  createdAt: '2021-07-31T02:36:41.144Z',
  updatedAt: '2021-07-31T02:36:41.144Z',
  lastViewed: '2021-07-31T02:36:41.144Z',
  textBin: 'U1YISS0uARIVJQA=',
  gDrive: false
}

I was then able to access the resultant brew via https://homebrewery.naturalcrit.com/edit/DomQTQp4BtO7 and https://homebrewery.naturalcrit.com/share/Hdpt5VKlbI1n.

[G-Ambatte]

Unless I've missed something, it doesn't currently seem possible to set authors: [] from the new Brew API; the current code checks for the existence of req.account and if found, sets authors: [req.account.username]. Attempting the following still results in a brew with authors: []:

const request = require('superagent');

const res = request.post('https://homebrewery.naturalcrit.com/api')
				.send({ title: "Test Title", text: "# Test Text", account: { username: "my_account_name" } })
				.catch((err)=>{
					console.log('Error creating Local Copy');
					this.setState({ errors: err });
					return;
				})
				.then(function(result) {
					console.log(result.body);
					return result;
				});

Following the /edit link and then saving the Brew updates the authors array to include the username.

[calculuschild]

That looks right. We probably don't want anyone to be able to create files on another person's account.

I'm not even sure what use case somebody would have to directly create documents in the database. Generating a brew to New? That makes more sense to me.

[G-Ambatte]

It should be possible to add parameters like title, text, style, etc. to /new (or a similar Route), allowing users to programmatically generate a New brew that can then be printed directly or saved to a HB user account.

[5e-Cleric]

I don't see why anyone would want that other than to use another UI to make documents. Considering closing this.

[dbolack-ab]

I don't see why anyone would want that other than to use another UI to make documents. Considering closing this.

Seconded.