API Blueprint Documentation for Stripe Subscription #402

mackenziehicks · 2016-10-27T19:02:54Z

What's in this PR?

Added endpoints( index, show, create, edit ) and data structures for the Stripe Subscriptions to the API Blueprint.

References

Fixes #391

Progress on: #245

amyschools · 2016-10-27T19:08:50Z

blueprint/api.apib

+ Response 200 (application/vnd.api+json; charset=utf-8)
+
+    + Attributes (Stripe Subscription Response)
+


If user should be authorized, do you need 401/403 repsonses?

amyschools · 2016-10-27T19:10:54Z

blueprint/api.apib

+    + Attributes (Record Not Found Response)
+
+### Update a Stripe subscription [PATCH/subscriptions/{id}]
+


I think there should be a space between PATCH and /subscriptions.

amyschools · 2016-10-27T19:11:50Z

blueprint/api.apib

+ `current-period-start`: `2016-07-08T03:03:51.967Z` (string)
+ `customer-id-from-stripe`: 'cus_9RnUvtsb41mD1g'  (string)
+ `ended-at`: null(string)
+ `id-from-stripe`: `sub_9RnVc9Cd03wV8X` (string, required)


Maybe add a comment that this is the subscription id assigned by Stripe.

amyschools · 2016-10-27T19:13:05Z

blueprint/api.apib

+ `cancelled-at`: null (string)
+ created: `2016-07-08T03:03:51.967Z` (string)
+ `current-period-end`: `2016-07-08T03:03:51.967Z` (string)
+ `current-period-start`: `2016-07-08T03:03:51.967Z` (string)


How is this different from start below?

amyschools · 2016-10-27T19:13:38Z

blueprint/api.apib

+ type: `stripe-subscription` (string, required)
+
+##Stripe Subscription Resource (object)
+ include Stripe Subscription Resource Identifier


Spacing after ## here and at 2721

amyschools · 2016-10-27T19:15:06Z

blueprint/api.apib

+
+ Response 200 (application/vnd.api+json; charset=utf-8)
+
+    + Attributes (Stripe Subscription Response)


Plural Stripe Subscriptions?

amyschools · 2016-10-27T19:15:36Z

blueprint/api.apib

+
+ Response 200 (application/vnd.api+json; charset=utf-8)
+
+    + Attributes (Stripe Subscription Response)


Should this be plural Stripe Subscriptions?

coveralls · 2016-10-27T21:41:09Z

Coverage increased (+0.2%) to 95.082% when pulling 7693d63 on 391-apiblueprint-stripesubscription into 98b3bbd on develop.

joshsmith

Lots of minor comments/suggestions here:

joshsmith · 2016-10-27T22:20:27Z

blueprint/api.apib

@@ -1407,7 +1407,15 @@ Stripe Subscriptions allow us to charge a customer's card on a recurring basis.

 + Response 200 (application/vnd.api+json; charset=utf-8)

-    + Attributes (Stripe Subscription Response)
+ Attributes (Stripe Subscriptions Response)


Looks like this got unindented somehow.

joshsmith · 2016-10-27T22:20:47Z

blueprint/api.apib

+
+ Response 403 (application/vnd.api+json; charset=utf-8)
+
+    + Attributes (Forbidden Response)




You can remove one line here.

joshsmith · 2016-10-27T22:22:17Z

blueprint/api.apib

+
+This endpoint is for creating, editing and returning Stripe Subscriptions.
+
+Stripe Subscriptions allow us to charge a customer's card on a recurring basis. A subscription ties a customer to a particular plan.


Prefer lowercase "subscriptions" in the descriptions here.

I would also state that our default here is monthly, that we're using $0.01 cent plans, and doing some X multiplier on top of that to set the actual amount.

I would also link to the Stripe docs from here.

joshsmith · 2016-10-27T22:23:09Z

blueprint/api.apib

+
+ Response 403 (application/vnd.api+json; charset=utf-8)
+
+    + Attributes (Forbidden Response)


I would remove the list all per some recent conversation about just having filters instead.

joshsmith · 2016-10-27T22:23:26Z

blueprint/api.apib

+            Accept: application/vnd.api+json
+            Authorization: Bearer {token}
+
+


Extra line in here.

joshsmith · 2016-10-27T22:24:24Z

blueprint/api.apib

@@ -2565,6 +2712,47 @@ This endpoint allows you to check whether a username is valid (by running a vali
 + data(array[Stripe Plan Resource], required)
 + include JSON API Version

+## Stripe Subscription Attributes (object)
+ `cancelled-at`: null (string) - If the subscription has been canceled, the date of that cancellation.
+ created: `2016-07-08T03:03:51.967Z` (string)


I would add the description we have for created elsewhere, specifying this is the date on Stripe's system.

joshsmith · 2016-10-27T22:24:56Z

blueprint/api.apib

+ `cancelled-at`: null (string) - If the subscription has been canceled, the date of that cancellation.
+ created: `2016-07-08T03:03:51.967Z` (string)
+ `current-period-end`: `2016-07-08T03:03:51.967Z` (string) - End of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.
+ `current-period-start`: `2016-07-08T03:03:51.967Z` (string) - Start of the current period that the subscription has been invoiced for


I would make this an actual month distance for clarity's sake.

joshsmith · 2016-10-27T22:25:29Z

blueprint/api.apib

+      + `active`
+      + `past_due`
+      + `canceled`
+      + `unpaid`


I think prefer alpha ordering here. What do you think?

This is the order listed on the Stripe API, I'm thinking because of the order that the status is likely to have. But could do Alpha instead.

joshsmith · 2016-10-27T22:25:44Z

blueprint/api.apib

+    + `stripe-plan`
+        + data(Stripe Plan Resource Identifier)
+    + `stripe-customer`
+        + data(Stripe Customer Resource Identifier)


Alpha ordering.

joshsmith · 2016-10-27T22:25:56Z

blueprint/api.apib

+ include JSON API Version
+
+## Stripe Subscriptions Response
+ data(array[Stripe Subscription Resource], required)


I think the required isn't necessary.

coveralls · 2016-10-27T22:42:53Z

Coverage increased (+0.2%) to 95.082% when pulling 0c3bd59 on 391-apiblueprint-stripesubscription into 98b3bbd on develop.

joshsmith · 2016-10-27T23:02:42Z

Rebase and squash!

added filter to 'list all Stripe subscriptions' added list all subscriptions, changed title of filter changes from 1st code review fixes after 2nd review

coveralls · 2016-10-27T23:26:58Z

Coverage remained the same at 95.082% when pulling e32c002 on 391-apiblueprint-stripesubscription into 3581955 on develop.

mackenziehicks added the awaiting review label Oct 27, 2016

mackenziehicks changed the title ~~391 apiblueprint stripesubscription~~ API Blueprint Documentation for Stripe Subscription Oct 27, 2016

amyschools suggested changes Oct 27, 2016

View reviewed changes

amyschools added needs submitter response and removed awaiting review labels Oct 27, 2016

amyschools approved these changes Oct 27, 2016

View reviewed changes

amyschools removed the needs submitter response label Oct 27, 2016

joshsmith requested changes Oct 27, 2016

View reviewed changes

mackenziehicks added the awaiting review label Oct 27, 2016

joshsmith removed the awaiting review label Oct 27, 2016

joshsmith approved these changes Oct 27, 2016

View reviewed changes

joshsmith added the ready to merge label Oct 27, 2016

API Blueprint Documentation for Stripe Subscription

e32c002

added filter to 'list all Stripe subscriptions' added list all subscriptions, changed title of filter changes from 1st code review fixes after 2nd review

mackenziehicks force-pushed the 391-apiblueprint-stripesubscription branch from 0c3bd59 to e32c002 Compare October 27, 2016 23:23

mackenziehicks merged commit 9e3302f into develop Oct 27, 2016

mackenziehicks deleted the 391-apiblueprint-stripesubscription branch October 27, 2016 23:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API Blueprint Documentation for Stripe Subscription #402

API Blueprint Documentation for Stripe Subscription #402

mackenziehicks commented Oct 27, 2016

amyschools Oct 27, 2016

amyschools Oct 27, 2016

amyschools Oct 27, 2016

amyschools Oct 27, 2016

amyschools Oct 27, 2016

amyschools Oct 27, 2016

amyschools Oct 27, 2016

coveralls commented Oct 27, 2016

joshsmith left a comment

joshsmith Oct 27, 2016

joshsmith Oct 27, 2016

joshsmith Oct 27, 2016

joshsmith Oct 27, 2016

joshsmith Oct 27, 2016

joshsmith Oct 27, 2016

joshsmith Oct 27, 2016

joshsmith Oct 27, 2016

mackenziehicks Oct 27, 2016

joshsmith Oct 27, 2016

joshsmith Oct 27, 2016

coveralls commented Oct 27, 2016

joshsmith commented Oct 27, 2016

coveralls commented Oct 27, 2016

		+ Response 200 (application/vnd.api+json; charset=utf-8)

		+ Attributes (Stripe Subscription Response)

		+ Attributes (Record Not Found Response)

		### Update a Stripe subscription [PATCH/subscriptions/{id}]


		+ Response 403 (application/vnd.api+json; charset=utf-8)

		+ Attributes (Forbidden Response)


		This endpoint is for creating, editing and returning Stripe Subscriptions.

		Stripe Subscriptions allow us to charge a customer's card on a recurring basis. A subscription ties a customer to a particular plan.

		Accept: application/vnd.api+json
		Authorization: Bearer {token}

API Blueprint Documentation for Stripe Subscription #402

API Blueprint Documentation for Stripe Subscription #402

Conversation

mackenziehicks commented Oct 27, 2016

What's in this PR?

References

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coveralls commented Oct 27, 2016

joshsmith left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coveralls commented Oct 27, 2016

joshsmith commented Oct 27, 2016

coveralls commented Oct 27, 2016