Document `/instances` POST (and other) format

[amark]

I'm trying to avoid using Express as a dependency.

Is it a urlencoded format? I hope so, because that would be pretty easy to handle.

It'd be really nice if there was mock requests I could test against before deploying, to make sure it is correct.

[amark]

anybody (?)

I'd like to finish this before the Netlify July Announcement.

[DavidWells]

Hey Mark.

If you give me your live endpoint I can set you up with an add-on sandbox where you can exercise live calls against it.

Shoot me email with the base endpoint. ( yoururl.com )

The payloads are documented in here: https://github.com/netlify/addons#add-on-api

GET yoururl.com/manifest       # returns the manifest & configuration details for your service
POST    yoururl.com/instances      # create a new instance of your service
GET     yoururl.com/instances/:id  # get the current configuration of an instance
PUT     yoururl.com/instances/:id  # update the configuration of an instance
DELETE  yoururl.com/instances/:id  # delete an instance

[amark]

@DavidWells thanks!

That is the problem, I'm trying to test locally before deploying (I'm fast at local dev, sadly slow at remote)... the docs don't say if the POST/PUT body are application/x-www-form-urlencoded format or other.

[amark]

So for instance, is there a NodeJS library you are using to send/issue the POST/PUT requests to addon provider URLs? Then I could just try creating mock POSTs locally from that library to my local dev server.

[DavidWells]

The POST is raw JSON

[amark]

@DavidWells thank you.

BEAUTIFUL, I was able to remove all dependencies, use raw NodeJS, and mock the calls locally. Turns out it wasn't too hard, other than flipping figuring out how on earth to send raw POST data - for some reason, this was hard to find on google/stackoverflow, IDK maybe just me? so I'm gonna put this here for others:

// FROM BROWSER CONSOLE
var xlsx = {};
var xhr = new XMLHttpRequest();
xhr.open('POST', '/instances'); // change to your URL!
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onload = function() { console.log(this.response) };
xhr.send(JSON.stringify({
  // Unique ID generated by Netlify
  uuid: '2e65dd70-523d-48d8-8826-a93229d7ec01',
  account: '5902622bcf321c7359e97e52',
  config: {
    site_url: 'https://calling-site-from-netlify.netlify.com',
    jwt: {
      secret: 'xyz-netlify-secret'
    },
    // User defined configuration values
    config: {
      name: 'woooooo'
    },
    // Netlify Site id
    site_id: '2e65dd70-523d-48d8-8826-a93229d7ec01',
    // Your service ID slug
    service_id: 'express-example',
    service_instance: {
      config: { name: 'woooooo' }
    },
    // If your add-on needs to trigger site rebuilds we will send a build hook
    incoming_hook_url: 'https://api.netlify.com/build_hooks/123xyz'
  }
}));

~ modified from https://stackoverflow.com/a/38799088/342275

in NodeJS on a http createServer req,res handler:

  var body = '';
  req.on('data', chunk => {
    body += chunk.toString();
  });
  req.on('end', () => {
    console.log(JSON.parse(body)); // assumes JSON!
    res.end('ok');
  });

~ from https://itnext.io/how-to-handle-the-post-request-body-in-node-js-without-using-a-framework-cd2038b93190

in case this helps anyone / docs / future reference.

[swyxio]

just curious, why was an express dependency so bad?

[amark]

@sw-yx because why use something that can be measured in megabytes that can be done instead in 173 bytes? I'd use it if I need it, but I don't need it to parse JSON.

@DavidWells I almost have my Netlify addon done, the frontend developer framework (JOY) finished, and just wrapping up these POST/PUT/manifest/etc. commands will send you the URL coming up.

When are you guys planning to announce? What else do I need to do in time?

[amark]

@sw-yx wound up using Netlify Functions ;) cause it was a bajillion times easier/simpler! Why use something when you can use Netlify instead! :D

@DavidWells submitted the addon! I'm excited for this to come to life. Please check in with me so I know what else needs to be done before launch. Thanks!

[swyxio]

@amark glad you found that working! yeah i think david actually has an example of how to make an addon just with netlify functions, i hope thats prominent enough in the instructions.

[amark]

@sw-yx yeah I skipped it at first then did a double take :P so epic! Thanks @DavidWells !

Did you guys get the addon submission? Pretty sweet I can inject modules for users right there, makes things easy-peasy for everyone! But I need to update my docs with netlify addons:create joy instructions, need to have it listed first tho and do final tests.