Docs: Partner: First pass at documenting endpoints by ebinnion · Pull Request #8865 · Automattic/jetpack

ebinnion · 2018-02-17T02:58:30Z

JPS v1 required hosting partners perform a lot of integration work setting up oAuth and then integrating in our APIs. We tried to simplify this as much as possible in JPS v2 by shipping two shell scripts that handle provisioning and cancellation of plans.

But, there are cases where a host may actually want to call the API instead of running a CLI command. For example, what if the site is already gone by the time the CLI command can be run?

It's currently pretty straightforward to cancel a plan by making calls directly to the API. A hosting partner simply needs to get an access token then call the cancellation endpoint, passing the domain and access token. That process is what is documented in this PR.

Provisioning a plan via calls directly to the API is much less straightforward. Currently, we require details such as the blog ID to be passed with the plan provisioning call, things that are better handled via the CLI.

For now, provisioning a plan is marked as TBD while we consider how to approach that.

To test:

Create a partner and key by following instructions here in PCYsg-emq-p2
Provision a plan manually via Jetpack Start and shell on WPCOM
Run through commands in this documentation to cancel the plan via the API

Changelog entery

We improved the documentation for partners so they're now able to get them right on the Jetpack's Github repository under the docs/partners directory.

oskosk · 2018-02-20T14:31:56Z

docs/partners/plan-provisioning-direct-api.md

+#### Response Parameters
+
+- __success__:       (bool) Was the operation successful?.
+- __error_code__:    (string) Error code, if any'.


Looks like this quote is not intended. There's one in the next line too.

oskosk

LGTM!

ebinnion · 2018-02-20T15:08:53Z

Thanks! I've pushed a commit to remove those quotations.

gravityrail

Looking good! Just a couple of minor stylistic changes.

gravityrail · 2018-02-20T16:59:44Z

docs/partners/plan-provisioning-direct-api.md

+
+When you become a Jetpack partner, we will provide you with your partner ID and a secret key. Typically you just pass these values directly in to the `bin/partner-provision.sh` and `bin/partner_cancel.sh` scripts. But, when calling the WordPress.com API directly, you'll first need to get an access token with for your partner ID with a scope of `jetpack-partner`.
+
+To do that, you'll make a `POST` request to the `https://public-api.wordpress.com/oauth2/token` endpoint passing with the request parameters mentioned below.


It's probably worth linking to https://developer.wordpress.com/docs/oauth2/ here for more information.

gravityrail · 2018-02-20T17:02:42Z

docs/partners/plan-provisioning-direct-api.md

+    --url https://public-api.wordpress.com/oauth2/token \
+    --header 'cache-control: no-cache' \
+    --header 'content-type: multipart/form-data;' \
+    --form client_id={PARTNER_ID} \


Is this intended to be shell-interpolated? If so, it should probably be written as ${PARTNER_ID} or $PARTNER_ID

Nope. I just meant it as a placeholder so the partner placed their ID there.

gravityrail · 2018-02-20T17:04:19Z

docs/partners/plan-provisioning-direct-api.md

+        'content-type': 'multipart/form-data;'
+    },
+    formData: {
+        client_id: {PARTNER_ID},


This is also not valid JSON (it should be obvious to most people, but still could be a cause of confusion), so maybe declare these as a const above with dummy values and reference them as real variables.

gravityrail · 2018-02-20T17:04:30Z

docs/partners/plan-provisioning-direct-api.md

+        client_id: {PARTNER_ID},
+        client_secret: {PARTNER_SECRET},
+        grant_type: 'client_credentials',
+         scope: 'jetpack-partner'


Extra spaces

gravityrail · 2018-02-20T17:04:58Z

docs/partners/plan-provisioning-direct-api.md

+
+### Cancelling a plan
+
+Cancelling a Jetpack for a given Jetpack site, as long as the partner making the cancellation request is also the partner that provisioned that plan, is fairly straightforward. To move forward, you'll need your partner secret as well as the URL of the site that you'd like to cancel the plan for.


Cancelling a Jetpack plan

This is also awkward wording in general, a bit longer than it needs to be. Maybe something like:

Plans can be cancelled by making a request using your Partner Token and the URL of the site being cancelled.

gravityrail · 2018-02-20T17:08:03Z

docs/partners/plan-provisioning-direct-api.md

+- __Method__: POST
+- __URL__:    https://public-api.wordpress.com/rest/v1.3/jpphp/{$site}/partner-cancel
+
+`$site` is the site's domain and path where `/` in the path is replaced with `::`. For example:


Maybe include an example with two slashes as well, like

example.com/demo/wp becomes example.com::demo::wp

gravityrail · 2018-02-20T17:08:56Z

docs/partners/plan-provisioning-direct-api.md

+
+```shell
+curl --request POST \
+    --url https://public-api.wordpress.com/rest/v1.3/jpphp/{SITE_DOMAIN}/partner-cancel \


Interpolation tweaks as per comment above

gravityrail · 2018-02-20T17:09:12Z

docs/partners/plan-provisioning-direct-api.md

+
+var options = {
+    method: 'POST',
+    url: 'https://public-api.wordpress.com/rest/v1.3/jpphp/{SITE_DOMAIN}/partner-cancel',


Interpolation tweaks as per comment above

Feedback has been addressed

gravityrail

Great! Thanks for the changes. 👍

* update changelog.txt * Update readme.txt with scaffolding for 5.9 changelog and release draft shortlink * Add changelog entry for #8243 * Add changelog entry for #8296 * Add changelog entry for #8367 * Add changelog entry for #8686 * Add changelog entry for #8707 * Add changelog entry for #8709 and #8714 * Add changelog entry for #8729 * Add changelog entry for #8777 * Add changelog entry for #8780 * Add changelog entry for #8786 * Add changelog entry for #8787 * Add changelog entry for #8801 #8805 #8832 #8865 and #8804 * Add changelog entry for #8817 * Add changelog entry for #8822 * Add changelog entry for #8823 * Add changelog entry for #8829 * Add changelog entry for #8834 * move some items to major enhancements * Add changelog entry for #8836 * Add changelog entry for #8839 * Add changelog entry for #8861 * Add changelog entry for #8862 * Add changelog entry for #8863 * Add changelog entry for #8866 * Add changelog entry for #8870 * Add changelog entry for #8874 * Add changelog entry for #8875 * Add changelog entry for #8881 * Add changelog entry for #8890 * Add changelog entry for #8911 * Add changelog entry for #8927 * Add changelog entry for #8931 * Add changelog entry for #8933 * Add changelog entry for #8930 * fix wording * typo * minor fixes * replace partner scripts for Jetpack Start in changelog entry * Update to-test.md * Update to-test.md * minor style fixes to to-test.md * minor style fixes to to-test.md * minor fixes on to-test.md * Add changelog entry for #8868 * Add changelog entry for #8844 * Add changelog entry for #8664 * Add changelog entry for #8935 * Add changelog entry for #8425 * Add changelog entry for #8625

Docs: Partner: First pass at documenting endpoints

3102029

ebinnion added [Status] In Progress Docs Jetpack Start labels Feb 17, 2018

ebinnion added this to the 5.9 milestone Feb 17, 2018

ebinnion self-assigned this Feb 17, 2018

ebinnion requested a review from jeherve as a code owner February 17, 2018 02:58

ebinnion added 6 commits February 16, 2018 20:59

Docs: Partner: Fix link to other partner provision doc

2029cc5

Docs: Partner: Fix API method

c3fbe01

Docs: Partner: Add docs for getting jetpack-partner scope token

b546f79

Docs: Partner: Add examples for cancelling a plan

ac4ebca

Docs: Partner: Formatting fixes for jetpack-partner token examples

577596f

Docs: Partner: Remove redundant request parameters

52403ea

ebinnion force-pushed the add/jps-v2-api-direct-docs branch from e8b4149 to 52403ea Compare February 19, 2018 22:12

ebinnion added 2 commits February 19, 2018 16:14

Docs: Partner: Formatting changes for extra readability

6991ebb

Docs: Partner: Fix url in plan cancellation domain example

f376b08

ebinnion requested a review from gravityrail February 19, 2018 22:23

ebinnion added [Status] Needs Review This PR is ready for review. and removed [Status] In Progress labels Feb 19, 2018

oskosk reviewed Feb 20, 2018

View reviewed changes

oskosk approved these changes Feb 20, 2018

View reviewed changes

oskosk added [Status] Ready to Merge Go ahead, you can push that green button! and removed [Status] Needs Review This PR is ready for review. labels Feb 20, 2018

Docs: Parter: Remove erroneous single quotes

f7bb8dd

gravityrail previously requested changes Feb 20, 2018

View reviewed changes

ebinnion added 3 commits February 20, 2018 11:17

Docs: Partner: Add link to oauth2 docs

90f5cfe

Docs: Partner: Properly interpolate in examples of plan provisioning

338d9af

Docs: Partner: Formatting/style tweaks

612c248

gravityrail approved these changes Feb 20, 2018

View reviewed changes

oskosk merged commit 38dea65 into master Feb 20, 2018

matticbot added the [Status] Needs Changelog label Feb 20, 2018

oskosk deleted the add/jps-v2-api-direct-docs branch February 20, 2018 19:19

jeherve removed the [Status] Needs Changelog label Feb 21, 2018

oskosk added the [Status] Has Changelog label Feb 27, 2018

oskosk added a commit that referenced this pull request Feb 27, 2018

Add changelog entry for #8801 #8805 #8832 #8865 and #8804

8d012f4

kraftbj removed the [Status] Ready to Merge Go ahead, you can push that green button! label Oct 13, 2020


		When you become a Jetpack partner, we will provide you with your partner ID and a secret key. Typically you just pass these values directly in to the `bin/partner-provision.sh` and `bin/partner_cancel.sh` scripts. But, when calling the WordPress.com API directly, you'll first need to get an access token with for your partner ID with a scope of `jetpack-partner`.

		To do that, you'll make a `POST` request to the `https://public-api.wordpress.com/oauth2/token` endpoint passing with the request parameters mentioned below.


		### Cancelling a plan

		Cancelling a Jetpack for a given Jetpack site, as long as the partner making the cancellation request is also the partner that provisioned that plan, is fairly straightforward. To move forward, you'll need your partner secret as well as the URL of the site that you'd like to cancel the plan for.

Conversation

ebinnion commented Feb 17, 2018 • edited by oskosk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changelog entery

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oskosk left a comment

Choose a reason for hiding this comment

Uh oh!

ebinnion commented Feb 20, 2018

Uh oh!

gravityrail left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gravityrail left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

ebinnion commented Feb 17, 2018 •

edited by oskosk

Loading