search

adlnet / xAPI-Spec

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

More Clear Documentation for APIs #896

Open DavidTPate opened 8 years ago

DavidTPate commented 8 years ago

As I've been digging more and more into the xAPI specification, it's become pretty clear to me that I have no clue how some of these APIs are supposed to work (specifically for Activity State, Activity Profile, Agent Profile, Activities, and Agents). None of them are standard REST (they all use query parameters to identify the target objects) and the description of them is very general and lacking in detail of how it should function.

I think that this is in general bad practice for an interoperability specification since this can lead to the APIs functioning differently per-implementation. I know previous we had brought up create swagger documentation for the APIs. I think this is all well and good, but a better approach would be pseudo-code of what should happen so that these APIs can (hopefully) work in similar manners between implementations.

One such example that I've found really useful is WhatWGs URL parsing where it walks step-by-step through the parsing process for a URL. This allows the implementation to be understood and implemented as it was intended.

I see that with v1.0.3 there's some additional language coming in around these APIs but I think it can still be improved as these descriptions are only handling the successful case, whereas things like a State not existing and executing a PUT (with the intention of updating it) are not described.

garemoko commented 8 years ago

Yes, 1.0.3 certainly does make these sections clearer but an example in an appendix wouldn't hurt if you'd like to create one.

I think the particular case of trying to update something that doesn't exist as an update is already covered by the concurrency section though. I'm not even sure how you'd get into the scenario of trying to update (but specifically not create) something that didn't exist as you'd need to have an etag.

DavidTPate commented 8 years ago

Yeah, there definitely starts to be some interesting edge cases that we are running into as we continue to scale up. I'll see what I can come up with to start putting something together so that we can start editing it and getting to the desired behavior of each of the APIs.

garemoko commented 8 years ago

@DavidTPate fancy taking a stab at a PR on this before 1.0.3 closes?

DavidTPate commented 8 years ago

Sure thing, @garemoko I'll take a look at the work that has already been done in the 1.0.3 branch and expand on it with some examples/clarification where possible. It's kind of open to interpretation in some areas right now, so I expect there will be some discussion around it once I finish that up (hopefully tonight).

garemoko commented 8 years ago

@DavidTPate poke! Are you still planning to take a look at this?

garemoko commented 8 years ago

@DavidTPate double poke!

garemoko commented 8 years ago

I propose closing this because there's nothing specific to address here.