search

netlify / open-api

Open API specification of Netlify's API
https://open-api.netlify.com/#/default
MIT License
260 stars 82 forks source link

Add code samples #192

Open ehmicky opened 5 years ago

ehmicky commented 5 years ago

One code sample for Node.js and Go for each operation would be a great addition to the documentation.

If we were to use Redoc (#182), this can be done using x-code-samples.

DavidWells commented 5 years ago

YES PLEASE!

ehmicky commented 5 years ago

This and #177 (adding descriptions) would be a major improvement of the API documentation IMHO.

However both are quite time-intensive tasks, which is why I put this as an issue not a PR. I'd be glad to do it, but I was thinking might more pressing things for me to work on (please let me know if I'm wrong).

Each of those tasks require going through every single endpoint, i.e. each might take 1 day at least, 2 days at most.

DavidWells commented 5 years ago

Yeah not mission critical at this juncture but would be nice to sprinkle them in over time.

Common api calls like createSite,updateSite,deleteSite,listSites, &getDeploy` might be a good place to add a couple to start

ramigs commented 4 years ago

Hello everyone!

Not sure if this fits better here or in netlify/js-client.

I've been playing around with the API and js-client for the last couple of weeks, and I think I can contribute with JavaScript code documentation, from the perspective of someone who's using js-client in Node.js.

The things I found most difficult, when I started learning how to use the client, was not having more code examples, specifically in terms of how to better do data flow control, and more complex use cases.

Maybe as @DavidWells suggested, starting with documenting the most common calls?

Where would the examples be added? This project or netlify/js-client? A revision/expansion to section Using Open API methods of README.md? Any section structure to be followed?

Let me know if I can help.

On another note, which would the project and best way to report possible issues in terms of API behavior? For example, I'm calling createSiteBuildHook() and its successfully creating the hook. However, title and branch parameters seem to be ignored, as the hook in the UI is created with empty name and branch.

verythorough commented 4 years ago

@ramigs That sounds great! Until we figure out exactly which tech we'll use for the open-api docs long term, I think adding the examples to the readme of the netlify/js-client repo is a nice way to get stuff up quickly.

In terms of reporting possible issues, it's possible to report in either repo, since the issues can be moved if necessary. I also recommend asking questions like that in the Netlify Community forums. The Netlify Support team is in there every day, and there are lots of community members who can help troubleshoot as well.

One quick tip in determining whether a problem is a bug in the API, the js-client, or your own code: if the thing you are trying to do can be done in the Netlify UI (like your build hooks example), the bug is probably not in the API itself, because the UI uses the API (check the Network tab calls 😉). If the thing can be done in the Netlify CLI (which uses the js-client), then it probably isn't the js-client (and you might check the CLI repo code to help troubleshoot your own js-client usage).

In the particular case of the build hooks, I haven't tried using the js-client createSiteBuildHook() method, but I can successfully make a POST to the build_hooks endpoint in Postman and have my title and branch set properly. I did have to send the payload as either form-data or x-www-form-urlencoded, though, so I suspect that you may not be passing your parameters to the function in the right format. I'll bet you could get some quick answers about that in the community forums.