Resultset API

From OSF Wiki
Jump to: navigation, search

The Resultset API is defined as a PHP class that should be used to manipulate a Resultset structure. A Resultset is a structure that defines all the results returned by any OSF Web Service. A Resultset is composed of a set of records, that we call subjects, that defines the information returned by the endpoint. A subject is composed of a series of attributes, that we call predicate, and a series of values, that we call objects.

A Resultset can be serialized in XML using the StructXML serialization format, or in JSON using the StructJSON serialization format.

The Resultset API gives you a series a utility functions that you can use to manipulate a Resultset structure. One of the main focus of the Resultset API is to give you access to a series of functions that enable you to serialize the Resultset in any of the following RDF serialization format:

Resultset Data Structure

A Resultset can be defined as a data structure composed of multiple arrays. The Resulset structure is defined as:

Array("dataset-uri" => 
     Array("record-uri" =>
      Array(
        "type" => Array(URIs...),
        "prefLabel" => "preferred label",
        "altLabel" => Array(alternative label literals...),
        "prefURL" => "http://preferred-url.com",
        "description" => "some description of the record",
        "other-data-attribute-uri" => Array(
          Array(
            "value" => "some value",
            "lang" => "language string of the value",
            "type" => "type of the value"
          ),
          Array(
            ...
          )
        ),
        "more-data-attribute-uri": Array( ... ),
        "other-object-attribute-uri" => Array(
          Array(
            "uri" => "some uri",
            "type" => "optional type of the referenced URI",
            "reify" => Array(
              "reification-attribute-uri" => Array("value of the reification statement"),
              "more-reification-attribute-uri" => Array( ... ),
            )
          ),
          Array(
            ...
          )
        )
        "more-object-attribute-uri": Array( ... ),
      ),
      "more-record-uri": Array( ... ),
    )
  )

As you can see the structure is a hierarchies of things:

  • Dataset
    • Subject
      • Predicate
        • Object
        • Object
      • Predicate
        • Object
    • Subject
      • Predicate
        • Object
  • Dataset
    • Subject
      • Predicate
        • Object

And so on...

The structure is as simple as this outline. We have subjects that are defined with multiple attribute/values. Then in the same resultset, we can have multiple subjects that come from different datasets.

Features

The Resultset structure support the following features:

  1. Description of subject records
  2. Each record have unique identifiers
  3. Each record have one or multiple types (belongs to one or multiple classes)
  4. Each record can be described with an unlimited number of data or object attributes
  5. Reification is supported on object attributes
  6. The value of data attributes can be defined with a type, or a lang tag.

API

The Resultset API is accessible via the Resultset class defined in the Resultset.php file. Additionally, the Resultset class is composed of a series of Subject instance which are defined by the Subject class in the Subject.php file.

By using these APIs, you will be able to create and manage resultsets of information that describes virtually anything you may think of. Additionally, you will be able to serialize that information in 6 different RDF serialization formats.

You will be able to use these APIs to manage any information returned by any OSF Web Service such as the CRUD: Read or Ontology: Read endpoints, or you will be able to use it to send records information to different OSF Web Service such as the CRUD: Create and CRUD: Update ones.