Merge pull request #1 from exonet/initial-release

Create initial release

Author: rsplithof

.coveragerc

@@ -0,0 +1,5 @@
+[run]
+source =
+    exonetapi
+omit =
+    tests/*

.editorconfig

@@ -0,0 +1,10 @@
+# http://editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

.gitignore

@@ -0,0 +1,11 @@
+*.pyc
+.idea/*
+*.egg-info/*
+dist/*
+
+# Unit test / coverage reports
+.tox/
+.coverage
+.coverage.*
+.pytest_cache/*
+/htmlcov/

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to `exonet-api-python` will be documented in this file.
+
+Updates should follow the [Keep a CHANGELOG](http://keepachangelog.com/) principles.
+
+## Unreleased
+[Compare v0.0.1 - Unreleased](https://github.com/exonet/exonet-api-python/compare/v0.0.1...develop)
+
+## [v0.0.1](https://github.com/exonet/exonet-api-python/releases/tag/v0.0.1) - 2018-??-??
+### Added
+- Initial release.

LICENSE.md

@@ -0,0 +1,21 @@
+# The MIT License (MIT)
+
+Copyright (c) 2018 Exonet <support@exonet.nl>
+
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in
+> all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+> THE SOFTWARE.

README.md

@@ -0,0 +1,70 @@
+Exonet API python package
+=========================
+
+.. image:: https://img.shields.io/pypi/v/exonetapi.svg?style=flat-square
+.. image:: https://img.shields.io/pypi/pyversions/exonetapi.svg?style=flat-square
+.. image:: https://img.shields.io/pypi/l/exonetapi.svg?style=flat-square
+
+Python 3 library for the Exonet API.
+
+Conventions
+-----------
+
+- Code style guide: PEP 8.
+- Docstring conventions: PEP 257 and reStructuredText.
+
+Install
+-------
+Install using pip::
+
+ pip install exonetapi
+
+Usage
+-----
+Example to get the user details of the authorised user::
+
+ from exonetapi import Client
+
+ # Create a new Client.
+ client = Client('https://api.exonet.nl')
+
+ # Authorize with a personal access token.
+ client.authenticator.set_token('<YOUR_TOKEN>')
+
+ # Make an API call. Get details of the authorized user.
+ user_details = client.resource('me').get()
+
+ # Print user's name.
+ print('Autorized as: {name}'.format(
+     name=user_details.attribute('name')
+ ))
+
+Please see the `/docs` folder for complete documentation and additional examples.
+
+Testing
+-------
+
+Run unit tests and coverage::
+
+ coverage run -m unittest discover tests -v && coverage html
+
+Change log
+----------
+
+Please see `CHANGELOG <https://github.com/exonet/exonet-api-python/blob/master/CHANGELOG.md>`_ for more information on what has changed recently.
+
+Security
+--------
+
+If you discover any security related issues please email `support@exonet.nl <mailto:support@exonet.nl>`_ instead of using the issue tracker.
+
+Credits
+-------
+
+- `Exonet <https://github.com/exonet>`_
+- `All Contributors <https://github.com/exonet/exonet-api-python/graphs/contributors>`_
+
+License
+-------
+
+The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

README.rst

@@ -0,0 +1,35 @@
+# Making API calls
+After the client has been initialised, use the `resource` method to define which type of resource you want to get from 
+the API:
+
+```python
+certificates_request = client.resource('certificates')
+```
+
+This will return a `RequestBuilder` instance on which additional request parameters can be set:
+
+```python
+# Define which filters must be applied:
+certificates_request.filter('expired', True)
+
+# Set the number of resources to get:
+certificates_request.size(10)
+
+# Set the page to get:
+certificates_request.page(2)
+```
+
+After setting the options you can call the `get()` method to retrieve the resource:
+```python
+certificates = certificates_request.get()
+```
+
+## Getting a single resource by ID
+If you want to get a specific resource by its ID, you can pass it as an argument to the `get` method:
+```python
+certificate = client.resource('certificates').get('VX09kwR3KxNo')
+```
+
+---
+
+[Back to the index](index.md)

docs/calls.md

@@ -0,0 +1,55 @@
+# Error handling
+
+For incorrect or failed requests the Exonet API will return exceptions or errors. In most cases this will be because
+invalid data is provided (validation) or because the authenticated user does not have the right permissions to make
+the request. These exceptions can be handled in the following way.
+
+## Default exception behavior
+A failed request will result in an exception containing the error message. The following example has no custom error
+handling and will throw an exception when the request fails.
+```python
+from exonetapi import Client
+
+# Create a new Client.
+client = Client('https://api.exonet.nl')
+
+# Login with machine token.
+client.authenticator.set_token('INVALID_TOKEN')
+
+# Try to make a request, will fail due to invalid token.
+myDetails = client.resource('me').get()
+```
+
+## Catching exceptions and outputting errors
+For validation exceptions you might be interested in the response body, since this can contain detail information about
+why the request was invalid. Catch the exception and output the request body containing the validation exception.
+
+```python
+from exonetapi import Client
+# Import the exception to catch.
+from requests.exceptions import HTTPError
+
+# Create a new Client.
+client = Client('https://api.exonet.nl')
+
+# Login with machine token.
+client.Authenticator.set_token('A_PREVIOUSLY_OBTAINED_TOKEN')
+
+try:
+    # Try to get a certificate while providing an invalid ID.
+    certificate = client.request('certificates').id('invalidID').get()
+except HTTPError as e:
+    print(e.response.text)
+    raise e
+```
+
+This will output the request body where the details of the error can be found:
+```
+{"errors":[{"status":400,"code":"101.10002","title":"request.invalidId","detail":"The id provided for 'certificate' is invalid.","variables":[]}]}
+
+requests.exceptions.HTTPError: 400 Client Error: Bad Request for url: https://api.exonet.nl/certificates/invalidID
+```
+
+---
+
+[Back to the index](index.md)

docs/error_handling.md

@@ -0,0 +1,7 @@
+# Exonet API Client Documentation
+
+- [Using this package](using.md)
+- [Making API calls](calls.md)
+- [Responses](responses.md)
+- [Error handling](error_handling.md)
+