Popit - user feedback

[petrus.j...@gmail.com]

Hi Guys,

I only recently started playing around with Popit, with the goal of seeing how I can integrate a parliamentary monitoring site to a Popit instance. But the experience is less than ideal at the moment.

A few things stand out:
> The behaviour of the API has changed, but without version numbers being updated. So on Thursday I spun up a new instance, and was running simple scripts against it, but by Monday the scripts were failing due to changes in the handling of authentication. Those types of changes should really be versioned, otherwise everything falls over, including your own client libraries.
> The API is not stateless: I found that I had to be logged-in on the website frontend in order to be able to send queries via the API (when using HTTP Basic Auth).
> The API is not secure, since it's hosted on http, not https. No matter how complicated the auth token handling might be behind the scenes, any intercepted request contains all of the info required to go and make changes to the database.
> Some of the API's responses can be misleading: I kept getting 404 (Not Found) responses whenever authentication failed. One would expect a 401 (Unauthorized). Little things like that can be big obstacles for outsiders who don't understand the internals of the system.
> The documentation is not hosted in the same place as the code, so with changes being made, it's difficult to know whether the docs are really up to date with the Master branch on Github. I would suggest hosting he docs in a directory of the same GitHub project and using a package like Sphinx to put it all together.

On a positive note, I was really surprised at how quick and easy it was to spin up a new instance. And I think that the frontend interface is pretty well done. Also, most of the big issues seem to revolve around authentication, which doesn't have to be very difficult to fix.

All of the best,
Petrus

[Chris Mytton]

Hi Petrus,

First of all thanks for your feedback, much appreciated. Sorry to hear
you've run into problems working with PopIt.

I've added some thoughts and responses inline below.

>> The behaviour of the API has changed, but without version numbers being updated. So on Thursday I spun up a new instance, and was running simple scripts against it, but by Monday the scripts were failing due to changes in the handling of authentication. Those types of changes should really be versioned, otherwise everything falls over, including your own client libraries.

Struan has written an explanation of this in the related ticket [1]
but to summarize, legacy login details should continue to work for the
time being (so existing scripts shouldn't break). New login details
can't be used for the API, instead you need to use an API token [2].

As we hadn't broken and existing scripts we didn't feel it was totally
necessary to bump the API version. We also really looked into our
options for bumping the API version from a technical point of view
yet, so there's a certain degree of putting it off until we really
have to :)

>> The API is not stateless: I found that I had to be logged-in on the website frontend in order to be able to send queries via the API (when using HTTP Basic Auth).

You shouldn't need to be logged into the front-end to use either
legacy credentials or an API token. However I believe if you're logged
into the front-end with a new site-wide account then you would indeed
be able to make API requests. Perhaps this is what has happened here?

It is our intention for the API to be completely stateless.

>> The API is not secure, since it's hosted on http, not https. No matter how complicated the auth token handling might be behind the scenes, any intercepted request contains all of the info required to go and make changes to the database.

Yep, completely agree with you on this point. We have a ticket open
for this [3] but not much has been done about this yet. I'll raise
this with the team in the next PopIt meeting and see if we can move
this forward.

>> Some of the API's responses can be misleading: I kept getting 404 (Not Found) responses whenever authentication failed. One would expect a 401 (Unauthorized). Little things like that can be big obstacles for outsiders who don't understand the internals of the system.

Yep, agreed. We're gradually ironing out problems like this as we go
along. I think this particular issue is a regression from when we
updated the auth system for site-wide account, so apologies for that.

>> The documentation is not hosted in the same place as the code, so with changes being made, it's difficult to know whether the docs are really up to date with the Master branch on Github. I would suggest hosting he docs in a directory of the same GitHub project and using a package like Sphinx to put it all together.

Funnily enough we actually used to have the documentation in the same
repo as the code [4]. I'm not sure there was any more of a guarantee
that the documentation would necessarily be up to date when it was in
the same repo ;) Perhaps including the date the documentation was
generated or similar would help indicate how up to date it was?


Hopefully this makes the changes we've made to the authentication
system a bit clearer. There are certainly some areas of the
documentation that still need updating/improving to make it easier to
figure out PopIt. We're still actively improving the API so
suggestions and feedback like this are all very welcome!

Thanks,

Chris

[1] https://github.com/mysociety/popit/issues/612#issuecomment-54443866
[2] http://popit.poplus.org/docs/api/#authentication
[3] https://github.com/mysociety/popit/issues/326
[4] https://github.com/mysociety/popit/commit/cb510e26b3ca08645bb0064b8e6cba5177e1094c

--
Chris

[Petrus Janse van Rensburg]

Thanks for the detailed feedback Chris. 

I'd say the most important changes to make at the moment would be to start hosting on HTTPS, and to fix Authentication: Personally, I feel strongly about handling the Auth token separately from the request body, in a dedicated header.

All of the best,

Petrus

[Chris Mytton]

Hi all,

Just wanted to post an update on this. As some of you might have already noticed, last week PopIt started redirecting to the secure https version of pages in the UI - https://popit.mysociety.org/instances. You should now see a padlock icon whenever you're browsing pages in the UI.

The API is also available over https and the documentation [1] has been updated accordingly. For the time being the API is also available over plain http. This is to prevent breaking backwards compatibility with existing clients. We strongly recommend switching scripts to use the secure https version of the API ASAP. It's likely that the next version of the API will only run over secure https.

Once you've switched to using the secure version of the API you might also want to regenerate your API key [2] to ensure it hasn't been compromised.

We've also made it possible to supply your API key in an `Apikey` header [3], this is now the recommended way of authenticating with the API.

Currently we're working on improving multi-language support in PopIt and adding support for Popolo's sources fields for attribution of data, we'll post a further update here once they've been deployed so interested folks can have a play.

Finally, thanks to everyone who's given us feedback and reported issues on PopIt, we really appreciate your efforts.

Cheers,

Chris

[1] http://popit.poplus.org/docs/api/

[2] https://popit.mysociety.org/apikey

[3] http://popit.poplus.org/docs/api/#authentication