resources-api-v1

The API specification to add content to the Schul-Cloud. This is the Resources API from the architecture. It should be the minimal example of what works for all content providers.

Communication

• If you like to work on this on bring in new ideas, you can open an issue and discuss with us.
• You can also join the mailinglist. The purpose of the mailinglist is to have another form of communication available which is more accepted than Github.

The design process follows the Collective Code Construction Contract.

Repository Structure

• api-definition
  Here, you can find the swagger API definition. You can try it out on swaggerhub. The api definition is incomplete and uses the resource json schema.
• schemas
  The resource schema is defined there. If you want to see what a resource looks like, you can find examples there. The schema can be used to verify objects if they can be used as a resource. If you write your own [crawler] (LINK: TODO), this may come in handy. The examples are tested and allow test-driven development of the schema. If you have additional ideas about what a resource is, you can submit it to there.
• generators
  These scripts use the swagger api definition to generate client and server libraries. Whenever the api changes, a python library is created and pushed to PyPI. You can use this library to access and test servers and resources.
• scripts and .travis.yml
  These scripts are used to run the continuous integration tests of the api to ensure it does not contain some obvious mistakes.

API

These are the API endpoints defined in the documentation.

Resources API

The resources API is specified in the api-definition. You can view it on swaggerhub. This API is tested and implemented by the schul_cloud_resources_server_tests. If you want to implement the API, please refer to the tests.

Errors follow the error schema.

Authorization

The API only specifies how to authenticate. Depending on the implementation, it differs where you get the authentication from.

A recommendation is that if you could not authenticate, the server shows a page telling you where to get accepted credentials.

The api specifies authentication via api key and basic authentication. If you want to add another authentication mechanism, please open an issue.

It is clearly defined how to do basic access authentication. Instead of no authentication and basic authentication, the Authorization header can be set to support api key authentication.

Example:

Authorization: api-key key=base64encodedkey

Because the Authorization header is used, one cannot authenticate with both, an api key and basic authentication.

Further Reading:

• http://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-auth-using-authorization-header.html
• http://www.ietf.org/rfc/rfc2617.txt via http://stackoverflow.com/a/11420667/1320237
• https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
• https://tools.ietf.org/html/rfc7235#section-4.2

Search API

This API is tested and implemented by the schul_cloud_search_tests. If you want to implement the API, please refer to the tests.

• GET /v1/search?Q=WORDS?filter[ATTRIBUTE]=...&filter[ATTRIBIUTE2]=...&page[offset]=SKIP?page[limit]=LIMIT
  Search for some words and filter the result.

  • Q (required)
    The query string WORDS. They should search at least these object attributes:
    • title
    • description
  • ATTRIBUTE (optional)
    To filter attributes of the objects, see the jsonapi definitions. Example: filter[title]=my%20title
    All objects returned must have the filter applied. Filtering must work with strings. It can work with other types. If an attribute is filtered which is an array, the value must be inside the array. If an attribute is filtered but not present, the object is not chosen. Example:

    objects: [ {"license": ["MIT", "GPL"]}, {"license": ["MIT"]} ]
    query: `?filter[license]=GPL`
    result:  [ {"license": ["MIT", "GPL"]} ]
    

  • pagination according to feathers.
    • page[offset] (optional)
      a positive integer
      how many object shall be skipped. If more objects are skipped than are there, data is empty.
    • page[limit] (optional) how many object shall be returned.
      This is the maximum number of objects that shall be returned. Less objects can be returned.

  Result:

  • See the examples
  • The schema for the body
  • Headers:
    • Content-Type: application/vnd.api+json
  • Errors, see the error schema:
    • 400
      also see error object on how to create informative errors about query parameters

      • unprocessable query parameters

      • sorting

        If the server does not support sorting as specified in the query parameter sort, it MUST return 400 Bad Request.

Related Work:

• Inspiration: feathers
• pagination inspired by feathers.

Research

DONE

• LOM
  LOM shall be an inspiration. Wikipedia
• Schema.org
  http://schema.org/docs/gs.html
  These schemata are used on web-sites to mark parts the of HTML site as specific content. This is useful if the search engine outputs HTML. E.g. an author can be shown in the Person schema.
  • schema.org: http://0.3-2e.schemaorgae.appspot.com/CreativeWork -> provider
• Learning Object
  https://en.wikipedia.org/wiki/Learning_object
  • IEEE LOM for
    • Learning object interactivity
    • 7. LangString
      • DateTime
      • Language
    • 5.2 Learning Resource Type
    • 5.1 Interactivity Type active, expositive, mixed
    • 5.9 Typical learning time
    • 5.8 difficulty
    • 5.7 typical age range

TODO

• bildungsserver, apache lucene, elixier - statt elastisearch
• Example: http://dsb-client.readthedocs.io/en/latest/descriptions.html

Automated Build

The automated build is done by Travis-CI. It does the following:

• Test the schemas for validity, usind the tests.
• Test the api-definition for validity.
• Generate a Python client. The client library is used by the server tests.

Further Reading

• README Driven Development
• HTTP statuses
• License Choice