Re: [MAWG-API] Further issues (was: Status code 206)

Hi Werner,

thank you for these comments, a mostly agree with them!

> - source format identifiers: The API document should contain a list of recommended identifiers for the formats considered in the API document, to ensure that uniform values are used for the source format (e.g., "mpeg7" vs. "mpeg-7").

In addition we could link to the identifiers given in the ontology document.

> - status code 404: The use of this status code also needs clarification. We propose the following: 404 should only be used when querying for specific properties, in case that one/several of those are not contained in the document. When quering for all properties, only those for which values exist shall be returned, but not others with status 404.

+1

> - multiple identifiers for resources or fragments: In some source formats, it could be possible to identify the resource or one of its fragments in multiple ways, e.g. by one or more identifiers, fragment name or temporal/spatial fragment URIs. In the RDF examples, this can be represented (as recommended in the guidelines) by using owl:sameAs. For an API implementation, we should require the querying by any of the valid identifiers must be supported.

Sorry, i do not get it - could you please clarify this?

> - API doc section 4.4.1: fragmentIdentifier is defined as "This attribute should be an URI determining the fragment for which the metadata is relevant." We propose to be more precise here and require this to be a complete URI, not just a fragment part.

+1

> - Fragments without identifiers: There are source formats, which may contain metadata about a fragment (e.g. a track) without specifying any kind of identifier for it. For the test suite, a workaround is to add an identifier, in order to ensure a reproducable test result. For the RDF representation this is not a problem, as blank nodes can be used.
> In an actual API implementation, an identifier generated by the API would have to be either deterministic or ensured to be valid for a certain time (e.g. a session). Consider e.g. the following case: a client requests all metadata for a video, and receives also metadata for the audio and video tracks. The tracks do not have any identifier in the source file, so the API generated it. If the client wants to query other metadata of these tracks later, it has to be ensured that the identifiers generated by the API are still valid.

I agree - we should keep this in mind to add this information to the test suite spec.

> Best regards,
> Martin and Werner
> 
>> -----Ursprüngliche Nachricht-----
>> Von: Florian Stegmaier [mailto:stegmai@dimis.fim.uni-passau.de]
>> Gesendet: Mittwoch, 21. Dezember 2011 12:38
>> An: public-media-annotation@w3.org
>> Betreff: [MAWG-API] Status code 206
>> 
>> Dear all,
>> 
>> while creating the JSON responses it was quiet unclear, how the status code
>> 206 should be used. I had a few discussions with Werner and Martin about
>> this. We have defined it as follows in the spec:
>> 
>> "206 - Partial Content - only a subset of the available data stored in the result
>> set"
>> 
>> There are quiet a few ways, how it could be interpreted.
>> 
>> Currently, code 206 (partial content) seems to be use in cases, where not all
>> fields of the response data structure are filled, as the information was not
>> present in the source document. IMO this is incorrect due to the following
>> reasons.
>> 
>> According to RFC2616, 206 is a partial GET request, i.e. only part of the
>> existing document is returned. Thus, 206 should in our case only be used. If
>> only part of the information in the source document can be returned. If all
>> information from the source document is returned, 200 should be used,
>> even if this does not fill all possible return values.
>> 
>> It is the usual case, that not all return values can be filled (e.g., language for
>> each and every property). Thus using not OK return code seems very
>> impractical, as an error status would be the default. Also, many of the
>> example JSON responses seem to fill these values with a kind of default
>> (e.g., set language to "en"). This should not be done, as it invents
>> information that is (i) not in the source document and (ii) optional. In such
>> cases, the respective attributes should not be returned.
>> 
>> To make this clear, the definition of this status code should be revised in the
>> API document.
>> 
>> For the test suite, both files (RDF as well as the examples) have to be taken
>> into account to ensure this behavior of 206. Further, we have to decide how
>> we handle a "known" loss of information. This is the case if we have a
>> mapping into our core ontology where the according property in the source
>> format is more specific.
>> 
>> Best regards,
>> Florian
>> _____________________________
>> Dipl. Inf. Florian Stegmaier
>> Chair of Distributed Information Systems
>> University of Passau
>> Innstr. 43
>> 94032 Passau
>> 
>> Room 248 ITZ
>> 
>> Tel.: +49 851 509 3063
>> Fax: +49 851 509 3062
>> 
>> stegmai@dimis.fim.uni-passau.de
>> https://www.dimis.fim.uni-passau.de/iris/
>> http://twitter.com/fstegmai
>> _____________________________
>> 

Received on Thursday, 22 December 2011 06:08:42 UTC