New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Should OCDS propose an API standard? #290

Closed
timgdavies opened this Issue Jan 19, 2016 · 14 comments

Comments

Projects
None yet
6 participants
@timgdavies
Copy link
Contributor

timgdavies commented Jan 19, 2016

A number of APIs are currently being developed to serve up OCDS data - each adopting their own approach.

The current documentation includes recommendations on data discovery, but stops short of proposals on how to construct an API.

This thread is for discussion of existing APIs and whether or not OCDS should propose common approaches for APIs.

@KrzysztofMadejski

This comment has been minimized.

Copy link

KrzysztofMadejski commented Mar 1, 2016

Of course! API standarization is just the next step of opening data.

Together with K-Monitor and other partners we're going to enhance http://www.redflags.eu/ portal, providing OCDS compliant data through API, so it would be good to join forces before starting development.

@timgdavies Could you provide a list of existing APIs / projects being developed?

I guess API should be built on top of more general aproaches like:

@timgdavies

This comment has been minimized.

Copy link
Contributor

timgdavies commented Mar 4, 2016

Exiting news on RedFlags.eu - would love to collaborate around this. What's your timeline looking like? We're thinking of having some co-working time around TransparencyCamp.eu at the start of June - so perhaps a good time to connect up?

In terms of existing APIs:

Open Procurement is a fully transactional API using OCDS building blocks, but not fully adopting the OCDS release structure yet. Support for that should be coming sometime later this year.

Colombia Compra were working on OCDS APIs. I'm not sure of the current state of this work.

The application which runs Montreal's Contract data portal provides OCDS output, although the internal data model is not OCDS

I suspect there are a few more things emerging out there, but these are the ones I know of so far.

@kindly was going to do a bit of looking at these over coming months as well, and might have some ideas from past projects of key things we need to think about here.

@akuckartz

This comment has been minimized.

Copy link

akuckartz commented Mar 6, 2016

No, please do not create yet another API. See this text by @RubenVerborgh :

The lie of the API
http://ruben.verborgh.org/blog/2013/11/29/the-lie-of-the-api/

@KrzysztofMadejski

This comment has been minimized.

Copy link

KrzysztofMadejski commented Mar 7, 2016

@akuckartz @RubenVerborgh

"If I really want to have unlimited json access, a developer can just write a script to convert the templated html into json. It’s not hard:" - wrong, writing and mainting scrapers is at least very time-consuming. And if the dataset is interesting people are doing it over and over again = waste of energy

For me standardised API means scalability. We want to expand RedFlags.eu to another countries. If we have country-specific OCDS-API-compliant data sources you don't need to do scraping, you just plug the datasource in. In RedFlag also country specific metrics need to be implemented, but in case of more general solutions (like SayIt) pluging the datasource in is all you have to do.

I'd like to see public institutions responsible for procurement to publish them through such API. We will push for that in Poland.

As to the mentioned double URL identifier problem: that's good use case. I agree that there should be one URL and Accept HTTP header support to know if clients want to download HTML or JSON (or XML).

@RubenVerborgh

This comment has been minimized.

Copy link

RubenVerborgh commented Mar 7, 2016

@KrzysztofMadejski That quote is taken out of context. You present it as an argument against a machine API, which it is not. Instead, It is an argument against having representation-specific API keys. The point was about information accessibility, not developer usability/maintainability. Given that we're not talking about API keys here, the other arguments in my post are much more relevant to this discussion.

For me standardised API means scalability.

It all depends on what aspect of scalability we are talking about. It might not scale in the number of different clients and servers, as it promotes a lock-step evolution model. It certainly does not scale in the number of standards.

My suggestion is that you:

  • create a list of features
  • see how existing API standards can realize those features

Making a new standard should be a last resort, not a first go-to.

@KrzysztofMadejski

This comment has been minimized.

Copy link

KrzysztofMadejski commented Mar 7, 2016

That's what we're planning to do (create a list of features + check existing APIs for those).

I do not want to make a new standard, but I strongly support OCDS should propose common approaches for API as the answer to question posed by @timgdavies in this thread.

Sorry @RubenVerborgh for scraping comment, I've missed the context (API keys to shield off json access are inneffective, because you can scrape anyways) by reading too fast.

It might not scale in the number of different clients and servers, as it promotes a lock-step evolution model. - could you elaborate?

@RubenVerborgh

This comment has been minimized.

Copy link

RubenVerborgh commented Mar 7, 2016

@KrzysztofMadejski Fully follow you there. Perhaps the title of this discussion is misleading then (I just got summoned here).

@KrzysztofMadejski

This comment has been minimized.

Copy link

KrzysztofMadejski commented Mar 7, 2016

@juzraai has just published RedFlags source code -> https://github.com/petabyte-research/redflags

@akuckartz

This comment has been minimized.

Copy link

akuckartz commented Mar 7, 2016

@RubenVerborgh Sorry for summoning you here. But there are not that many attempts at creating an "API standard" which begin with an open debate. We will see what will happen here.

@ekoner

This comment has been minimized.

Copy link

ekoner commented Apr 18, 2016

As part of our ongoing commitment to improving the OCDS, we are hosting an online community discussion around api specification.

When:
Tuesday, 26 April 2016 from 14:00 to 15:30 (BST)

Please sign up via Eventbrite: https://www.eventbrite.co.uk/e/ocds-api-specification-community-discussion-tickets-24734366155

@akuckartz

This comment has been minimized.

Copy link

akuckartz commented May 29, 2016

@ekoner What are the results of that discussion?

@ekoner

This comment has been minimized.

Copy link

ekoner commented May 31, 2016

@akuckartz following our community call, there's been interest in an api specification, so we've decided to go ahead with formalising this. A github repo will be set up specifically for discussions on api specification. In the meantime, please review or contribute to the specification document here: https://docs.google.com/document/d/14Zb5ZMYlLhhjf0c5JqhI7GxZ0umaa2qtdvTweGDmUik/edit?usp=sharing

@kindly

This comment has been minimized.

Copy link
Contributor

kindly commented Jun 7, 2016

There has been a start made to an API standard:

https://github.com/open-contracting/api-specification/

It is its in very early stages, but provides a framework for work on progressing this. It is based on feedback by looking at existing OCDS API implementations, other similar API standards and the community discussion.

All information is in the README.md of that repo and it is also the start of a more formal specification draft.

Any feedback, issues or suggestions about an API standard should be made in that repository from now on.

@ekoner

This comment has been minimized.

Copy link

ekoner commented Jun 22, 2016

Closing - please continue discussions in the new repo above.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment