Skip to content

Finalise query API for proposals as used in marketplace-like apps

Coming from some Proposals test cases offered by @lynnfoster, in response to work on CommonsPub by @mayel & Ivan (who doesn't yet seem to have an account here?)

The new additions look great, though there is some divergence from the spec in this that I would like to clean up since I am implementing much the same features at the moment.

primaryIntents & reciprocalIntents relationships

These are new fields with a bit of extra logic in them. The current way of accessing the Intent data is to go through Proposal.publishes.publishes, and then filter those results by the value of Proposal.publishes.reciprocal.

Are these simplified query edges something we think should be included in the core spec?

Proposal category

I like it as an idea but for me I think that's a display detail and not something I would want to put in the backend at this stage. Though it is the same logic as offersOnly and requestsOnly (below), might be an idea to have it in simply for those reasons.

Query fields

  • includeExpired and inScopeOf sound sensible, happy to add these. Presume default behaviour (without includeExpired) would be to omit proposals with hasEnd < now()? Or should the default be to return everything, and if you only want what's active then provide includeExpired: true? I suggest the latter would be a better general pattern to follow.
  • offersOnly and requestsOnly I basically have the same grammatic questions as "proposal category" above. Are these sub-groupings for "proposal types" something we can agree on as a core part of the spec?
  • location: I'd be happy to have this in there, but the way it would work with the expectations outlined by the GraphQL spec are that you would perform any more complex location-based queries against a dedicated location service, yielding a list of IDs for specific locations. You would then take those IDs and pass them into this query parameter to return any proposals which are located at the given locations. So, location should have the type [ID!] (an array of IDs). If CommonsPub are thinking to do geo-based queries directly from this endpoint then I think that's a more nonstandard approach.