subscriptions.json

[chadwhitacre]

We killed the tips.json API somewhere beneath #3399. We need to bring back a parallel API for subscriptions.

[kaguillera]

This should be blocked by the fact that a team page is needed before we add a subscription this widget to the team page (that does not currently exist).
Going to work on the Team profile page now

[rohitpaulk]

!m @kaguillera

[chadwhitacre]

I found a pretty nice way (IMO) to write literate APIs, but it got buried in a dead-end PR (see #3786 (comment) and, e.g., www/api/v2/index.spt). I have it in mind to rescue that work some day. Check it out if you're interested—but don't get too hung up on it if you're not. ;-)

[rohitpaulk]

Woah, that's some nice stuff :)

[chadwhitacre]

Thanks! :-) I thought it was a really interesting way to use simplates to integrate the API and documentation with the site itself.

[aandis]

Thinking of working on this next. Can someone point me in the right direction? :)
What are subscriptions? I don't see any relation in schema.sql. And what should subscriptions.json do?

[rohitpaulk]

@aandis - subscriptions is the user-facing term for payment_instructions in our schema. We used to offer an API endpoint for users to view and modify their tips (authenticated with their API keys). When we moved from tips to subscriptions (Gratipay 1.0 to Gratipay 2.0) - in the interest of velocity we didn't update the endpoint, thought we'd get back to it later someday (TODAY!).

So I poked up the the oldest tag (version) we have - https://github.com/gratipay/gratipay.com/tree/1840

I'd start by looking at %username/tips.json in the documentation under /https://github.com/gratipay/gratipay.com/tree/1840#api, and its corresponding implementation.

You could try checking out that version of the codebase, firing up the server and actually hitting the API to understand what it does - and maybe suggest improvements too :)

[rohitpaulk]

As of now, we want this information to be restricted to users via API keys - but in the future (if we land #236) it might make sense to expose some/all of this information publicly.

[rohitpaulk]

There was some nice stuff that people built on top of that endpoint, you might find them interesting -

http://ejohn.org/blog/gittip-at-khan-academy/
https://github.com/engineyard/gittip-collab

[aandis]

Cool! In the meanwhile, I managed to dig up tips.json before it got removed. From the looks of it, it offers GET and POST for modifying the db as you mentioned. So yeah, I'll start hacking on this. Thanks!

[aandis]

There was some nice stuff that people built on top of that endpoint.

I was wondering what the use case of this was. Thanks for pointing this out! :)

[rohitpaulk]

I was wondering what the use case of this was.

It could also come in handy if you (we) decide to build an android app for Gratipay ;)

[aandis]

That is more than enough to get me excited with this! :)

[aandis]

https://github.com/gratipay/gratipay.com/blob/master/www/%25team/payment-instruction.json.spt

Isn't this what this ticket is about?

[rohitpaulk]

That comes close, yes (it's no documented though, just used internally). One thing that lacks with that endpoint is - a user can't hit an endpoint to see all the subscriptions they've set up. If they know that they've setup a subscription to a certain team, then this endpoint could be useful.

In fact, we could just add an endpoint to view all subscriptions ~user/subscriptions.json, and redirect ~user/subscriptions/%team.json to %team/payment-instruction.json

Now that you know the functionality we intend to provide, what do you think is the best API design?

[aandis]

Ummm ok..

1. GET to ~user/subscriptions to get all subscriptions of a user.
2. GET to ~user/subscriptions with a team id as parameter to get information about a particular subscription. This request will be redirected to %team/payment-instruction.json
3. POST to ~user/subscriptions to create a new subscription. The team information will be in the body. This request will be also redirected to %team/payment-instruction.json

How does that sound?

[rohitpaulk]

with a team id as parameter

I think we'd want that to be the team slug :) This filtering is secondary though, as long as we expose all information through the batch endpoint (number 1, in your comment above)

This request will be redirected to %team/payment-instruction.json

You mean internal redirection and not client-side (via HTTP headers), right?

The above structure sounds good to me - Just 1 and 3 would do, in fact :)

Thoughts? cc: @whit537

[aandis]

You mean internal redirection and not client-side (via HTTP headers), right?

Yes. Although I am not entirely sure how this would work because I was playing around with tip.json in tag 1840 yesterday and couldn't get POST to work at all. All my POST were redirected by sub.spt after a 302 and becoming a GET. That is an internal redirect right?
Anyway, I came across this after a bit of research. So seems to me, it should have been returning a 307 to work properly.

I am still to test it with the current version though. I'll get started with this today and hopefully this doesn't happen.

[chadwhitacre]

One thing we had on the old tips.json was the ability to bulk update a bunch of tips in one POST. The Khan Academy setup used that, e.g.

[chadwhitacre]

@aandis Note that tip.json.spt (singular) is different than tips.json.spt (plural). Looks like we dropped the latter between 1831 and 1832:

https://github.com/gratipay/gratipay.com/blob/1831/www/~/%25username/tips.json.spt
https://github.com/gratipay/gratipay.com/blob/1832/www/~/%25username/tips.json.spt

The commit is 4d8700e and the PR is #3406.

[aandis]

Yep! I checked out both of them earlier. Working on subscriptions.json similar to tips.json now. :)

[chadwhitacre]

Cool. In #3460 (comment) you mentioned tip.json, so I wanted to make sure you weren't hitting a dead end because of that. :)

!m @aandis

[chadwhitacre]

!m @aandis

[chadwhitacre]

One ticket closer to landing the Pivot! :D

P.S. For context, we carved the Team Basics milestone out of the Pivot milestone at gratipay/inside.gratipay.com#383 (comment).