Skip to content
This repository has been archived by the owner on Mar 15, 2019. It is now read-only.

hpi-schul-cloud/resources-api-v1

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

resources-api-v1

CCCC draft Build Status PyPI npm (scoped)

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:

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:

Related Work:

Research

DONE

TODO

Automated Build

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

Further Reading