Skip to end of metadata
Go to start of metadata

Generic

  • REST
  • Json-based.  XML, YAML-support optional (determined by server).  Format determined by url parameter
  • Generic url structure: [http://api.example.com/version/resources{/id}
  • Four possible http return codes: 200 (ok), 401 (not authorized),  400 (generic client-side error), 500 (generic server-side error)
  • Paginate by url parameters limit and offset (0-based).  Default: limit=10, offset=0
  • Returned object structure: always 2 members: meta and data
  • meta always contains: numoffsettotal
  • data is always an array, even if it contains only a single object
  • Authorisation handled by OAuth2 (if required)
    • TODO: onderscheid tussen app-based authZ (voor telefoonboek etc), en personal data (authN required)
  • All strings: unlimited size, UTF8, unless otherwise specified
  • All integers: 32 bit signed, unless otherwise specified.  null==unknown
  • Follow URL-style json-api as much as practical (http://jsonapi.org/format/#url-based-json-api)

TODO: meta-endpoint for API-discovery:

  • Which API-resources are supported
  • Which API versions are supported
  • Which formats are supported

Types/objects definition:

Between brackets: the mapping to terms used in HORA: http://www.wikixl.nl/wiki/hora/index.php/Bedrijfsobjecten_onderwijs_en_onderwijsondersteuning

Objecten with their respective fields:

  • date:
    • string ISO8601: 2013-07-14
  • datetime:
    • string ISO8601: 2013-07-14T17:42+0200
  • building (--> gebouw):
    • naam
    • adres
    • lat
    • long
  • room (--> ruimte)
    • name
    • building
    • use?
  • course/module/unit (--> onderwijseenheid) (NB: distinction between available coures, and courses attended (currently and in the past))
    • name
    • type: enum {minor,course}
    • ects: int
    • subject: html
    • goals: html
    • requirements: html
    • costs: html
    • enrollment: html
    • literature: html
    • examDescription: html
    • contactHours: int
    • schedule: html
    • url
    • code
    • language: iso639-1 (2 chars)
    • level: enumerated {hbo-b,hbo-m,wo-b,wo-m}
    • educationType (educationFormat?)
    • organization (o?)
    • organizationalUnit (ou?)
    • teacher --> link to employee (?)
    • opleiding?
  • person (--> individu) (follow eduPerson specs?) (kan een persoon met twee types teruggeven, of twee losse records van dezelfde persoon)
    • type: enum{faculty, student, staff, alum, member, affiliate, employee, library-walk-in}
    • surname
    • listname
    • gender
    • title
    • email
    • telephoneNumber
    • mobile
  • student (~~> deelnemer)
    • person
    • studentNumber
    • opleiding (?)
    • group/klas/etc
  • employee (--> medewerker)
    • office
    • deparment/ou
    • employeenum
    • coursesTaught (?)
  • group (~~> leergroep) (how to handle roles?)
    • name
    • members (--> links to person)
    • subgroups (--> links to groups)
    • membersRecursed (--> links to person)
    • startDate
    • endDate
    • type (optional)
  • newsfeed
  • newsitem
  • test (-->toetsactiviteit)
  • testresult (-->toetsresultaat)
    • student --> link
    • course --> link
    • dateModified
    • description
    • testDate (dateTest?)
    • status: enum{concept,final}
    • grade: int
    • honoraryGrade: int
    • result: (passed, etc)
    • passed: bool
    • weigth: float, 0<x<1
    • subject (?)
    • teacher (?)
  • courseresult (-->onderwijseenheiresultaat)
    • student --> link
    • opleiding (?) --> link
    • course --> link
    • dateModified

/student/@me  (my personal info)
/student/@me/courses  (courses I've taken)

/courses/ (all available courses)
/courses/MATH-101 (detailed info about course MATH-101)

/results/@me (list of status of all my courses, incl results)
/results/@me/MATH-101 (list of tests for MATH-101)

/newsfeeds/ (list of all available newsfeeds)
/newsfeeds/faculty:ABC (newsfeed for faculty ABC), etc

/people/?q=piet  (search for people student+staff called Piet)
/people/piet@harderwijk.edu (details about specific person)

/groups/ (list of all public groups) is this useful?
/groups/someGroup (details, incl members+subgroups of someGroup)
/groups/someGroup?recurse=1 (like above, but add membersRecursed, which contains all members of group+subgroups+subsubgroups+etc)

/rooms/ (list of all rooms).

  • No labels