Backend TM3 API - Documentation and Feedback

[bgirardot-np]

The documentation for the TM3 backend API is available here:

http://tasking-manager-staging.eu-west-1.elasticbeanstalk.com/api-docs

Please add any feedback or needs on this issue thread.

[bgirardot]

From @danbjoseph:

Are there plans to have api functionality for getting the status of all the squares for a task and who completed/validated squares etc?

[danbjoseph]

stuff like list of projects, state of tasks, etc. like from TM2

[bgirardot]

More from Dan: we use the current TM api to get info on all the missing maps tasks https://github.com/AmericanRedCross/osm-data-parse/tree/master/tasking-mgr-projects

[bgirardot]

The existing TM2 API is here: https://github.com/hotosm/osm-tasking-manager2/wiki/API

[bgirardot]

From Tyler: For example list all projects by status with associated metrics, list all users with associated metrics. Right now if I want something basic like how many projects did we work on this year it requires sql I believe.

[smit1678]

I'm assuming that some of this will be integrated once the Contribute page is further developed. But listing out a couple things that would be useful for integrations with other applications:

• List of all projects
• List of all projects with a certain tag (portfolio)
• List of active tags or portfolios
• Project complete stats
• Per user stats of projects, completed squares, and timestamps: User stats json osm-tasking-manager2#758

Other questions

Do we want HTML in the return? I'm assuming would be nice to not have to strip HTML if you want to pull a project description or title into another application.

[bgirardot]

Yes, no html, json objects is my understanding.

[hunt3ri]

Yes can confirm API speaks only JSON :)

[danbjoseph]

the same data used to build the Activity and Stats tabs in the current tasking manager, if that data could be publicly accessible through the API, that'd be great.

[hunt3ri]

One thing to think about as I've mentioned to @bgirardot is API authentication.

Presumably these endpoints should require a token, and if so we'd need some sort of auth scheme. Most simply that would be storing a timebased token in the DB. However, we would need a CRUD page for creating tokens for trusted consumers.

[danbjoseph]

What about just imposing traffic limits for users? A couple of endpoints on the current TM are open? (I know almost nothing about this, so please ignore if I'm making no sense.)

[cgiovando]

Can we can include time/date metadata for each project exposed via API? Would be useful to list and retrieve all projects created in a specific data range or per year.

[mikelmaron]

Why are we concerned about tokens for read access on general stats? Is there really a realistic possibility of abuse?

I do see value in tokens for write access -- could be pretty interesting to think about what's possible for API access to create/modify projects, and change state on task squares, etc.

[hunt3ri]

@mikelmaron I agree if API is read-only - authentication is less of a concern. If everyone is happy for the data to be open to the world. (Data is worth $$$ these days :)

One thing I'd recommend thinking about if the API is open is the potential impact on DB perf. Stats usually necessitate reasonably complex queries involving full table scans which would likely hammer the DB if you had a lot of callers scraping stats out of the API.

So a rate-limiting / caching approach should be agreed.

[ViolaineDo]

One thing would be cool for facilitating interaction with github : to move the protocol to https. It would also secure the process...

[hunt3ri]

TM3 will be HTTPS compliant from launch :)

[d3netxer]

It was discussed to break up this issue into separate issues for the API after our meeting last week. I'll start doing this.