docs: projects API examples

[aeneasr]

Related Issue or Design Document

Closes ory/network#217

Checklist

• I have read the contributing guidelines and signed the CLA.
• I have referenced an issue containing the design document if my change introduces a new feature.
• I have read the security policy.
• I confirm that this pull request does not address a security vulnerability.
  If this pull request addresses a security vulnerability,
  I confirm that I got approval (please contact [email protected]) from the maintainers to push the changes.
• I have added tests that prove my fix is effective or that my feature works.
• I have added the necessary documentation within the code base (if appropriate).

Further comments

[vinckr]

Its great that we have this now, but I would prefer if we dont add a new page.
We already have too many pages in the docs which clutters the sidebar and makes it hard to navigate - can we find a way to add this example somewhere else?

I would prefer in the update to the Projects API blogpost (PR is open here: https://github.com/ory-corp/web/pull/2018)

This is not the hardest API to use, so IMO its fine to have examples only in the blog and in the docs only reference.

[aeneasr]

I thought it needs to be in the docs for it to appear in kapa? I'm fine adding all project management to one page or just updating the project API docs

[aeneasr]

We will however need to have some type of user guide "delete project" that person X can send to person Y (owner of the org) so they can do it easily (in the future in the UI).

[vinckr]

maybe instead of updating the blogpost, we just move the content into the docs as a projects API examples/snippets doc? We also have example for organizations already (so the same API) we can merge all of it in one doc and then link to it as required.
WDYT? Happy to do it in this PR.

we can feed the blogposts also to kapa, that is no issue.

[aeneasr]

I was always frustrated by CockroachDB because they hide a lot of developer content (e.g how replication works) in blog posts, and it was difficult to find it. So I agree that it maybe makes sense to have one or two pages in the docs to talk about different use cases like:

A guide to manage your project using the API (create, update, patch delete) with the various options (cli, api, sdk, console)

[vinckr]

Ok, I will port over my content from the blogpost to this PR. Should not take too long.

[vinckr]

Added the other content and turned the doc into a general guide for that API.
I had to tweak the command a little for it to work on my machine (specifically put the ${API_KEY} into " instead of '), might be due to the terminal I am using?

The delete API didnt work AFAICT though.

[aeneasr]

The delete API didnt work AFAICT though.

I fixed it, which is why I'm documenting it :)

[aeneasr]

One could also argue that this instead would belong to the API docs. Like Stripe does it: https://docs.stripe.com/api/subscriptions/cancel

Because really, this is API documentation.

[vinckr]

One could also argue that this instead would belong to the API docs. Like Stripe does it: https://docs.stripe.com/api/subscriptions/cancel

Because really, this is API documentation.

True its already documented there (minus snippets).
This is why I put it on the blog originally, we can still move it there as tutorial.

[aeneasr]

Let's merge this so that it's in the docs and then we can still move it to API docs.