Metadata-Version: 1.0
Name: schul_cloud_ressources_api_v1
Version: 1.0.0-49
Summary: Schul-Cloud Content API
Home-page: https://github.com/schul-cloud/ressources-api-v1
Author: UNKNOWN
Author-email: UNKNOWN
License: UNKNOWN
Description: schul_cloud_ressources_api_v1
        =============================
        
        The ressources API package allows easy access to the Schul-Cloud ressources servers.
        To get an overview about how the api is defined, please refer to the repository_.
        
        Installation
        ------------
        
        You can install the package with pip from PyPI_
        
        .. code:: shell
        
            pip install schul_cloud_ressources_api_v1
        
        Accessing the API
        -----------------
        
        Suppose, a server runs under http://localhost:8080/v1.
        You can use the api to connect to it.
        If you do not have a server, you can get a test server from the package
        `schul_cloud_ressources_server_tests`_.
        
        .. code:: Python
        
            # import the api classes for access
            from schul_cloud_ressources_api_v1 import ApiClient, RessourceApi
        
            # create the client objects
            url = "http://localhost:8080/v1"
            client = ApiClient(url)
            api = RessourceApi(client)
        
        The `api` object gives access to the server.
        Here, you can see how to access the api:
        
        .. code:: Python
        
            # import the ressource examples
            from schul_cloud_ressources_api_v1.schema import get_valid_examples
        
            # get a valid ressource
            ressource = get_valid_examples()[0]
            print(ressource)
            
            # add the ressource to the server
            response = api.add_ressource(ressource)
        
            # verify the ressource is on the server
            all_my_resssources_on_the_server = api.get_ressource_ids()
            assert response.id in all_my_resssources_on_the_server
        
            # get the ressource from the server
            ressource_copy = api.get_ressource(response.id)
            assert ressource_copy == ressource
        
            # delete the ressource
            api.delete_ressource(response.id)
        
        Authentication
        ~~~~~~~~~~~~~~
        
        There are these options for authentication:
        
        - no authentication: this is the default and nothing needs to be done.
        - basic authentication: authentication with user name and password
        - api_key authentication: a key is supplied to authorize the requests.
        
        The authentication is a global state.
        All ``ApiClients`` use this global state.
        Thus, you can only authenticate at one API at a time.
        
        .. code:: Python
        
            import schul_cloud_ressources_api_v1.auth as auth
        
        You can remove all authentication. This is the default case.
        
        .. code:: Python
        
            auth.none()
        
        You can authenticate with username and password. This is `Basic Authentication
        <https://en.wikipedia.org/wiki/Basic_access_authentication>`.
        
        .. code:: Python
        
            auth.basic("username", "password")
        
        You can authenticate with an api key.
        
        .. code:: Python
        
            auth.api_key("your-api-key")
        
        
        Verifying Ressources
        ~~~~~~~~~~~~~~~~~~~~
        
        When you use ressources, you may want to verify if they have the correct format.
        The format is specified in the `ressource-schema <https://github.com/schul-cloud/ressources-api-v1/tree/master/schemas/ressource>`_.
        This schema is included in the api.
        
        .. code:: Python
        
            from schul_cloud_ressources_api_v1.schema import (
                get_valid_examples, get_invalid_examples, validate_ressource, is_valid_ressource
            )
        
        You can test if a ressource is valid or not using `is_valid_ressource`
        
        .. code:: Python
        
            valid_ressource = get_valid_examples()[0]
            assert is_valid_ressource(valid_ressource)
        
            invalid_ressource = get_invalid_examples()[0]
            assert not is_valid_ressource(invalid_ressource)
        
        If you would like to find out more about why the ressource is not valid, you can use `validate_ressource`.
        
        .. code:: Python
        
            validate_ressource({'title': 'hello'})
        
        Which results in an error that the `url` property is not present but is required.
        
        .. code:: Python
        
            jsonschema.exceptions.ValidationError: 'url' is a required property
            
            Failed validating 'required' in schema:
                {'properties': {'contentCategory': {'$ref': '#/definitions/ContentCategory'},
                                'contextUrl': {'$ref': '#/definitions/URL'},
                                'curricula': {'items': {'$ref': '../curriculum/curriculum.json'},
                                              'type': 'array'},
                                'dimensions': {'$ref': '#/definitions/Dimensions'},
                                'duration': {'type': 'number'},
                                'languages': {'description': 'As described in IEEE '
                                                             'LOM, Section 1.3 '
                                                             'http://129.115.100.158/txlor/docs/IEEE_LOM_1484_12_1_v1_Final_Draft.pdf',
                                              'items': {'$ref': '#/definitions/Language'},
                                              'type': 'array'},
                                'licenses': {'items': {'$ref': '../license/license.json'},
                                             'type': 'array'},
                                'mimeType': {'description': 'https://tools.ietf.org/html/rfc2046',
                                             'example': 'text/html',
                                             'type': 'string'},
                                'size': {'format': 'int64', 'type': 'integer'},
                                'thumbnail': {'$ref': '#/definitions/URL'},
                                'title': {'description': 'The title of the ressource.',
                                          'example': 'Schul-Cloud',
                                          'type': 'string'},
                                'url': {'$ref': '#/definitions/URL'}},
                 'required': ['title',
                              'url',
                              'licenses',
                              'mimeType',
                              'contentCategory',
                              'languages'],
                 'type': 'object'}
            
            On instance:
                {'title': 'hello'}
        
        Related Packages
        ----------------
        
        The `Server Tests <https://github.com/schul-cloud/schul_cloud_ressources_server_tests>`_ use this library to test servers implementing the API defined in the repository_.
        
        Further Reading
        ---------------
        
        - To edit this description, you can edit the `file on Github <https://github.com/schul-cloud/ressources-api-v1/tree/master/generators/python_client/README.rst>`__.
          You can use `this editor <http://rst.ninjs.org/>`__.
        
        
        
        
        
        
        
        .. _repository: https://github.com/schul-cloud/ressources-api-v1
        .. _PyPI: https://pypi.python.org/pypi/schul-cloud-ressources-api-v1
        .. _schul_cloud_ressources_server_tests: https://github.com/schul-cloud/schul_cloud_ressources_server_tests
        
Keywords: Swagger,Schul-Cloud Content API
Platform: UNKNOWN
