search

adlnet / xAPI-Spec

The xAPI Specification describes communication about learner activity and experiences between technologies.
https://adlnet.gov/projects/xapi/
908 stars 404 forks source link

Non-sequitur in Part 3, 2.1.2 #943

Closed fugu13 closed 8 years ago

fugu13 commented 8 years ago

Part 3, 2.1.2 (3.2.1.2? Very weird to have the numbers reset), https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI-Communication.md#212-post-statements , covers POSTing statements, but there's this block of text as the majority of the description:

An alternative for systems that generate a large amount of Statements is to provide the LRS side of the API on the AP, and have the LRS query that API for the list of updated (or new) Statements periodically. This will likely only be a realistic option for systems that provide a lot of data to the LRS.

I think I understand how this got in there, looking back historically, but right now it reads very confusingly. The section on the details of POSTing statements spends most of its descriptive text opining on how an LRS client might manage its internal logic, and talking about the LRS "querying" the external API -- something completely unrelated to POSTing statements, and an operation contemplated but not described in the spec.

I think we can just strike that whole paragraph. What would be more useful is a brief description of when POSTing statements might be a good choice, highlighting the differences between POST and PUT.

garemoko commented 8 years ago

I'm OK with removing this, but if others think it's useful, could we just add "Note:" in front to separate it from the short description?

I don't think a discussion of the differences between POST and PUT is useful given that we already say "Learning Record Providers SHOULD POST Statements including the Statement "id" property instead of using PUT."

andyjohnson commented 8 years ago

We've gotten in the habit of calling these parts 1,2, and 3. Really we just have to start calling them "About", "Data", and "Communication". We could consider phasing the "Part" language out of the TOC.

andyjohnson commented 8 years ago

Per the 7/6/16 call, tag the language as a Note: (clarifying language welcome if it is still confusing), also eliminate the wayward "AP"

fugu13 commented 8 years ago

The part I quoted in the issue? That part isn't clarifying -- it doesn't have anything to do with POSTing to an LRS at all, or even anything that's possible without making an LRS with functionality beyond what's in the spec -- not really something the spec can clarify.

garemoko commented 8 years ago

Good point about it requiring additional LRS functionality. I'm also not aware of anybody implementing this for the reasons outlined (though I am aware of implementations taking this approach for otehr reasons).

I'm going to go ahead and PR a removal.

garemoko commented 8 years ago

PR merged. Can this be closed?

garemoko commented 8 years ago

Let's close this.