Basic API

[iangreenleaf]

A proper API can come later, but for the moment we probably need to at least replicate the existing junky API so that the iPhone apps and clans don't needlessly die. We can probably leave this until closer to launch and evaluate the landscape at that point.

[jamesprior]

What are the iPhone apps that are there now? There is http://grinnellplans.com/iphone/ which uses the api but really, a mobile layout on regular plans would do about 178% of what that does now and without an API.

[iangreenleaf]

There's that one, and there have been a couple ideas from current students to build new ones, though so far there haven't been any finished products. And then there's @baldwint's Clans command-line client, and maybe one other project that I'm forgetting?

So when we get close to launch, we can ask the questions of how much traffic any of these clients see and if it would be a huge disservice to cut them off. Certainly I would prefer not to replicate the gross legacy API in Rails, but I'm also looking to make this transition not too disruptive, so it really depends on what the full impact would be.

[PsychicNoodles]

This should probably involve making new resources (maybe with this library?) so there doesn't need to be a check in every controller method. If there is a library that allows multiple possible controllers per route then that would probably work for most routes as JSON apis tend to be CRUD-based like Rails.

[PsychicNoodles]

Also, an api is a good pursuit if only to enable interested programmers (like me ✋) to experiment and build apps or scripts. I'll admit, I don't know of any apps that exist right now, but there absolutely are/will be people who want to use the api. I don't know if it should be a particularly high priority, but it's definitely something that should be done.

[iangreenleaf]

@PsychicNoodles Yeah, building a proper API is a very high priority for projects we tackle after launch, but that's a bigger undertaking. I'll definitely give you a poke when we start thinking about that, because I would love to have someone working on a client app to test out the API, give feedback, etc.

For the moment, though, I'm looking to do the minimum necessary to get us to feature-parity so we can launch, which either means re-creating the crappy old API, or scrapping it entirely.

[iangreenleaf]

Heh, @jamesprior you wrote the iPhone client, didn't you? I just figured that out. I guess if the creator of the client isn't too concerned about us cutting off access, it's probably okay.

What about you, @baldwint? Will you be heartbroken if we cut off Clans at some point, with the understanding that one of our first post-launch priorities will be providing a proper API that you can re-target against?

[jamesprior]

Yeah, I clearly haven't done much with the client in years. It's main selling points are screen size formatting and low data consumption. Those were pretty important eight years ago but don't offer much today.

To be clear, I'm talking about the iPhone web app hosted at http://www.grinnellplans.com/iphone/ - if there's a native app out there using the API that's something else. The web app could just get replaced with any mobile friendly css and nobody would miss it.

On Mar 8, 2016, at 8:02 PM, Ian Young [email protected] wrote:

Heh, @jamesprior you wrote the iPhone client, didn't you? I just figured that out. I guess if the creator of the client isn't too concerned about us cutting off access, it's probably okay.

What about you, @baldwint? Will you be heartbroken if we cut off Clans at some point, with the understanding that one of our first post-launch priorities will be providing a proper API that you can re-target against?

—
Reply to this email directly or view it on GitHub.

[niqjohnson]

I've only been half-following development here (looks awesome, by the way!), but I just wanted to jump in and add that, among many of the heaviest Plans users I know (myself included), @jamesprior's iPhone web app is essential. I think a non-trivial percentage of active users will FREAK OUT if there's no small-screen-friendly version of Plans ready when the switchover happens.

I agree that making the base Plans app fully responsive is the best path, but I know how much work that takes (I've toyed with creating a responsive stylesheet a few times in the past and then quickly got overwhelmed). That said, I think that either having a responsive stylesheet or creating enough of an API to keep the iPhone web app working at launch will be a must-have for many very active users.

[jamesprior]

Okay, one thing I haven't checked on is how does the new version of plans look like on small devices? I know there has been discussion of keeping backwards compatibility with stylesheets so I assume the rest of the CSS is about the same, and consequently the mobile formatting is mostly unchanged. Is that right?

If so it seems like the choice becomes making a mobile version or moving existing styles to Zurb / Bootstrap / FrameworkThatDoesMobile.

[iangreenleaf]

Thanks for the feedback! Let's explore responsive CSS in #132. If we can figure out a way to provide decent small-screen support in the web view at launch without disrupting too much other stuff, we'll do that and drop the API. If that task has a longer timetable, we'll recreate the API to keep the iPhone client going.

[baldwint]

The old JSON API lacks feature parity with the Plans web interface, so clans mostly does not use it. The only exception is the autofinger list (clans list), which does use the API.

Once upon a time, that particular endpoint had a bug which caused the lists to be in a different order when served by the API vs. the web interface. Basically, the API code had a SQL query in it that wasn't kept up to date with the corresponding query that renders the web interface. I fixed the bug, but I didn't trust the API after that, and I implemented the rest of clans' functionality by just scraping data out of HTML.

So, I could accomodate the passing of this old API with relatively little work, and with no love lost from me. However I'm concerned that if we leave the new API to be a post-launch priority, it'll either (A) never get done, or (B) end up having the same buggy, tacked-on feeling that the old one did, due to having features added to it haphazardly as required by clients.

In my view, the best way to make sure Plans has a complete and reliable API is for the web interface itself to be a consumer of that API. Maybe that ship has sailed, architecturally, but it seems like if we put a thin JSON-encoding wrapper around each of the data model functions, we would already be running laps around the old API in terms of completeness and reliability. Is that feasible to accomplish before launching?

I think the decision to drop the old API is a good one, but I'd be disappointed to see it go before a new one is ready to take its place.

[iangreenleaf]

@baldwint I think that ship has sailed to a large degree. While that sort of arrangement certainly has some nice properties, it would also complicate the architecture, make change more difficult, and make it harder for new people to get involved. My stance on these decisions is often cruelly pragmatic, since given our small developer base and time commitments, Plans will probably never be a project of pure architectural beauty.

Your concerns are very valid, but I do have some mitigation measures in mind. I am determined to make sure that (B) doesn't happen—a large part of the reason that I'm not considering a new API as a feasible pre-launch option is because that would rush it. I will be taking a personal interest in building it properly and versioning it for future improvement. And (A) is always a concern, since things move slowly in general on this project, but I would say the API is easily in the top 3 on my list of post-launch priorities. It's probably the most-requested thing on our list, so I'd say it has a pretty decent chance of getting built.