···
On 20 November 2012 12:44, Chris Ford cford@thoughtworks.com wrote:
I added an issue suggesting a single format for people to comment on.
Should I also do one for the proposal to exclude searching/filtering/pagination? I would argue that we should preserve one case of filtering, that is a feed of updates. That will allow clients of the API to know what to refresh. Alternatively, we could require the server to set cache headers to let the client know how often it needs to re-request data.
One thing that’s not quite clear to me from the documents - is the format of a collection of facilities and a single facility the same? Did we discuss and reject the idea that the collection could simply be an index?
Cheers,
Chris
On 16 November 2012 05:58, Bob Jolliffe bobjolliffe@gmail.com wrote:
Some minor suggestion to tidy up the structure which is currently a little mixed up.
Three major headings:
- Intro - some short introductory blurb about the purpose of the document
- move sample docs under here
I don’t want submit this as a diff because it might cause some conflicts. Matt if you agree you can do this. But if you can’t (and I know you have a lot going on) then we can discuss on the call tomorrow and if everyone is agreeable I’ll make these adjustments. As you know I don’t want to edit the document directly.
Alternatively we can just build up the agreed list of changes and you might get to them next week.
Cheers
Bob
–
–
Thanks for that. We had a call on Friday (just Kelly, me and Justin unfortunately) to discuss where we are currently so that Justin can get moving formalizing the docs.
Was hoping Kelly would have summarized (he does it better than me), but this is the gist:
-
we agreed with all of your proposals re versioning, single format and searching/filtering/pagination
-
we were a bit hamstrung about updating the document as Matt is travelling.
-
Justin was going to start work on the formal specification document ASAP ie. without waiting to tidy up everything in the draft document.
-
we decided we should move the repo into a more “formal” home rather than in Matt’s home github. Consequently I have just setup https://github.com/facilityregistry. I have moved my old stuff into there and Matt will move his when he gets to sit down. And I see Justin has started by creating a folder.
I think it would be a good idea for you to capture your proposal as an issue as things get buried in the email.
The idea of an index (I presume you mean an abbreviated list containing probably just names and identifiers) hasn’t been discussed as far as I recall, but it is something I have been thinking too. Often times, a client might want to simply get the list of facilities without all the detail. In fact for many integration scenarios it might only be this index that clients will ever need. For example, to post an ANC dataset from a mobile phone to DHIS, it is not necessary or useful to know how many beds, the colour of paint in the wards, electricity supply etc. What you need is the identifier of the facility to be used in the dataset. If this is along the lines you are thinking, then post an issue for this one too.
For the moment keep posting issues to Matt’s github. We’ll let you know as soon as it has moved.
Regards
Bob
On 15 November 2012 11:32, Bob Jolliffe bobjolliffe@gmail.com wrote:
Hi Matt and all
Thanks for summarizing this. I had some brief chats with Kelly in Indianapolis about the best way to reduce scope to get a version out the door. Unfortunately Ed had already left and I know peoples availability is about to become difficult - I have some free space next week but seems I might be alone on that.
I am still stranded in Philly so I’ll try and generate some diffs to the document which incorporate some ideas for wrapping up. Then you can consider applying them.
BTW that issue of “mine” was something I carved off the email from Chris Ford earlier in the week. Kelly and I started the process of mining the comments we had on the mailing list and turning them in to issues on github but only got as far as the first one 
Which I actually think looks like a reasonable resolution of that outstanding concern.
Would be great to do the same with the rest of the very valuable input we’ve seen coming in over the last month or two on the list but not sure if that is the best use of the few hours of time I have right now. Now that we have started using github it would be good to start getting all the feedback into some simple structured form (even simple github issues are fine) in case we start to lose track of the input we are getting.
Few small comments inline.
On 15 November 2012 00:01, Matt Berg mlberg@gmail.com wrote:
Dear All,
I just wanted to provide a few updates on behalf of the team on our recent progress.
New API Reference Website
First, we created a website for the API and have been moving the content from the google doc over to it. The google doc, while providing a great white board for discussion, is a bit unweidly and this will provide a lot better way to structure and update the API docs moving forward.
The new API docs can be found here:
https://facility-registry-api.readthedocs.org/en/latest/api_specifications.html
Moving forward this will represent the canonical source for the docs and where we will document changes in API.
The source for the docs are available here:
https://github.com/mberg/fred-api/tree/master/docs
Later we will create a fred github user but for now if you want permission to make edits please just let know. Note: all commits immediately trigger an update on the docs site.
We still need to decide on a website URL for the project site. Paul can you go ahead and get facilityregistry.org?
Draft API
We are relatively close but have a few outstanding issues we need to resolve.
- Core properties: an initial set have been identified. We still need community review and feedback to see if anything is missing.
- Identifiers
We are getting quite a bit of feedback in favour of the initial approach of <identifier …/><identifier …/>
I’m happy to revert to this if Ed and others are happy.
- API Calls: we cleaned this section up a lot and reverted back to a more traditional URI calls. Please review but things should be close to final here.
- Sample Payloads - an initial version has been proposed
- Authentication - HTTP basic initially
Issues that need resolution
Not my proposal but see above.
- **default document structure - **we’ve agreed to try and support both XML and JSON. The case has been made numerous times that it might be simplest to support only one format initially. This would probably be xml as it’s a bit more descriptive but we need consensus on this.
- schema definition for properties - we have been considering either a schema or xform approach to define the structure of the facility properties. We still need to agree on something here. It’s a possibility we address this issue after this initial draft.
We won’t agree on this in the time available. And maybe that is not a bad thing. So we create some text saying that the hosting application needs to have a metadata endpoint(s) which clients can use to determine the syntax of the properties. That might be through schema, codelists, xforms or what have you. We tighten this up for the next version.
Issues we will likely tackle in upcoming releases:
I think we need to tackle this one more importantly than many of the others. The point has been made by others that retroactively tacking on versioning is not a good position to be in. So we need to agree this one now. I’ll take a closer look at what Chris has suggested and propose a diff based on that.
Extreme case scenario of having a spec that says … any content … but is clear about versioning, evolution, extension and backward compatibility is better than having richly defined content but no notion of how to deal with relationship with the next version. I’ll make a priority of proposing some text here based on Chris’ comments this afternoon.
- reporting / aggregation layers
- full text and spatial search
I think, unless we have another 3 weeks to hammer this stuff out, which we don’t, we scope both of these and the specification about filtering and searching syntax, out for this version. Which is not to say applications can’t offer this functionality, but we can leave that open how they do it for now. There are too many options to consider in too short a time.
Bob
Please chime in if I missed anything. Feedback is welcome.
Thanks,
Matt
–