# apteco-api
A Python wrapper package for the Apteco API to allow access to Apteco Marketing Suite™ resources.
This package is auto-generated from the API specification,
with a Python class for each API model and a Python method call for each API endpoint.
It enables the user to interact with the API using pure Python,
and transforms Python method calls with Python objects into HTTP requests with JSON,
including deserializing the responses back into Python objects.
The [**apteco**](https://pypi.org/project/apteco/) package builds further on this
to provide a rich API for creating FastStats selections, data grids and cubes,
including returning results directly as pandas DataFrames.
**Note:** although this package is auto-generated, which should minimise the chance of bugs occurring in it,
some parts of it are untested and there remains the possibility of bugs caused by inconsistencies in the API specification
or errors in the API itself. If you do come across a bug or any unexpected behaviour,
please contact Apteco support (support@apteco.com)
or [open a GitHub issue](https://github.com/Apteco/apteco-api/issues/new/choose).
## Details
This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
- API version: v2
- OrbitAPI spec version: 1.9.19.6190
- Package version: 0.3.1
- Build package: `org.openapitools.codegen.languages.PythonClientCodegen`
- Generator version: 4.3.1
## Requirements
- Python 2.7 and 3.4+
- Access to an installation of the Apteco API
The Apteco API, which also goes under the name **Orbit API**, is part of the Apteco Orbit™ installation.
If you are unsure whether you have access to this, please contact Apteco support (support@apteco.com).
*Note: the examples in this guide use Python 3.6+*
## Installation & Usage
You can install the package the usual way from PyPI using `pip`:
```
pip install apteco-api
```
Import the package in Python using:
```python
import apteco_api
```
*Note: the package follows the Python convention of a hyphen `-` in the package name
and underscore `_` in the import name.*
## Getting Started
The examples below shows how to connect to the API, log in to create an access token,
retrieve some data from one of the API's endpoints, and then log out.
*Note: your login credentials (`my_username` and `my_password` below)
are the same credentials you would use to log in to your FastStats system or Apteco Orbit™.*
### Logging in
```python
import apteco_api as aa
# configure the API client to use your instance of the API
config = aa.Configuration(host='https://example.com/OrbitAPI')
api_client = aa.ApiClient(configuration=config)
# send a simple login request
sessions_controller = aa.SessionsApi(api_client)
login_response = sessions_controller.sessions_create_session_simple(
'my_data_view', 'my_username', 'my_password'
)
# keep a copy of the session ID (needed to log out)
session_id = login_response.session_id
# update the configuration with your credentials
config.api_key={'Authorization': login_response.access_token}
config.api_key_prefix={'Authorization': 'Bearer'}
```
Since the `config` object updated here is the configuration object for `api_client`,
the latter will now be authorised to access the API.
### Retrieving data from an endpoint
This code retrieves a list of tables in the `Holidays` system on the given DataView:
```python
tables = aa.FastStatsSystemsApi(api_client).fast_stats_systems_get_fast_stats_tables(
'my_data_view',
'holidays'
)
print(f"There are {tables.count} tables in the Holidays system:")
print('\n'.join(t.name for t in tables.list))
```
**Output:**
```commandline
There are 9 tables in the Holidays system:
Households
People
Bookings
Communication Responsible
Insurance
Communications
Content
Responses Attributed
Journey History
```
### Logging out
You can end your session using the `logout_session` endpoint,
and passing in the session ID returned from the logging in process above:
```python
aa.SessionsApi(api_client).sessions_logout_session('my_data_view', session_id)
try:
tables = aa.FastStatsSystemsApi(api_client).fast_stats_systems_get_fast_stats_tables(
'my_data_view',
'holidays'
)
except aa.ApiException as e:
print(f"{e.status}: {e.reason}")
```
**Output:**
```commandline
401: Unauthorized
```
The first line successfully ended the session and so, as expected,
the attempt to retrieve the tables data failed and raised an exception.
Note that logging out like this ends the session on the server-side,
but it doesn't remove the copy of the (now invalid) access token kept in the
`api_client.configuration` object.
## General use of the API client
Every section of the API (`Audiences`, `FastStatsSystems`, `Queries`, `Sessions`, etc)
has a corresponding controller class in the `apteco-api` package, named `<section>Api`
e.g. `SessionsApi`, as seen above.
To use endpoints from a given section,
create an instance of the controller by passing an \[authorised\] `ApiClient` object
as the single argument to its constructor:
```python
queries_controller = aa.QueriesApi(api_client)
```
This object then has a method corresponding to each endpoint of that section of the API,
which can be called as a normal Python function.
```python
query_result = queries_controller.queries_perform_query_file_count_synchronously(
'my_data_view',
'holidays',
query_file=aa.QueryFile('Private/Bookings to France or Germany.xml')
)
```
Some of the parameters for this function may need to be specific object types;
in the example here, the first two parameters are strings specifying the DataView and FastStats system to use for the query,
while the path of the file for the query is given via a `QueryFile` object supplied as a keyword-only argument.
The `QueryFile` object itself is initialised with a single argument, namely the filepath.
Similarly, the function call returns a Python object.
These API functions often return 'result' objects which bundle together various data and metadata as attributes,
and these attributes can then be accessed to obtain the information of interest.
```python
count = query_result.counts[0]
print(f"The query matched {count.count_value:,} {count.table_name.lower()}.")
```
**Output:**
```commandline
The query matched 985,734 bookings.
```
### Further details
All classes and methods have detailed docstrings providing further information about their parameters and return values.
You can also explore the API in a visual way by going to `/swagger/ui/index.html` from your API base URL,
e.g. `https://example.com/OrbitAPI/swagger/ui/index.html`
Here, each section of the API is listed, and clicking on one will expand the view
to show all the endpoints that belong to it.
Clicking on an endpoint will similarly expand that to detail its parameters
and show example values for using it.
You can also try out endpoints directly within the interface,
and view the returned data.
## Author
Apteco Ltd
support@apteco.com
Raw data
{
"_id": null,
"home_page": "https://www.apteco.com/",
"name": "apteco-api",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Apteco,Apteco API,Apteco Marketing Suite,Apteco FastStats,FastStats,Apteco Orbit,Orbit,OpenAPI,OpenAPI-Generator,Swagger,Swagger API,API,REST",
"author": "Apteco Ltd",
"author_email": "support@apteco.com",
"download_url": "https://files.pythonhosted.org/packages/71/73/5cdbcd9ba88a82555c4a5fc501ae8d250cd326b2b26b66b03f1198dce1f7/apteco-api-0.3.1.tar.gz",
"platform": null,
"description": "# apteco-api\nA Python wrapper package for the Apteco API to allow access to Apteco Marketing Suite\u2122 resources.\n\nThis package is auto-generated from the API specification,\nwith a Python class for each API model and a Python method call for each API endpoint.\nIt enables the user to interact with the API using pure Python,\nand transforms Python method calls with Python objects into HTTP requests with JSON,\nincluding deserializing the responses back into Python objects.\n\nThe [**apteco**](https://pypi.org/project/apteco/) package builds further on this\nto provide a rich API for creating FastStats selections, data grids and cubes,\nincluding returning results directly as pandas DataFrames.\n\n**Note:** although this package is auto-generated, which should minimise the chance of bugs occurring in it,\nsome parts of it are untested and there remains the possibility of bugs caused by inconsistencies in the API specification\nor errors in the API itself. If you do come across a bug or any unexpected behaviour,\nplease contact Apteco support (support@apteco.com)\nor [open a GitHub issue](https://github.com/Apteco/apteco-api/issues/new/choose).\n\n## Details\n\nThis Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:\n\n- API version: v2\n- OrbitAPI spec version: 1.9.19.6190\n- Package version: 0.3.1\n- Build package: `org.openapitools.codegen.languages.PythonClientCodegen`\n- Generator version: 4.3.1\n\n\n## Requirements\n\n- Python 2.7 and 3.4+\n- Access to an installation of the Apteco API\n\nThe Apteco API, which also goes under the name **Orbit API**, is part of the Apteco Orbit\u2122 installation.\nIf you are unsure whether you have access to this, please contact Apteco support (support@apteco.com).\n\n*Note: the examples in this guide use Python 3.6+*\n\n\n## Installation & Usage\n\nYou can install the package the usual way from PyPI using `pip`:\n\n```\npip install apteco-api\n```\n\nImport the package in Python using:\n\n```python\nimport apteco_api\n```\n\n*Note: the package follows the Python convention of a hyphen `-` in the package name\nand underscore `_` in the import name.*\n\n\n## Getting Started\n\nThe examples below shows how to connect to the API, log in to create an access token,\nretrieve some data from one of the API's endpoints, and then log out.\n\n*Note: your login credentials (`my_username` and `my_password` below)\nare the same credentials you would use to log in to your FastStats system or Apteco Orbit\u2122.*\n\n### Logging in\n\n```python\nimport apteco_api as aa\n\n# configure the API client to use your instance of the API\nconfig = aa.Configuration(host='https://example.com/OrbitAPI')\napi_client = aa.ApiClient(configuration=config)\n\n# send a simple login request\nsessions_controller = aa.SessionsApi(api_client)\nlogin_response = sessions_controller.sessions_create_session_simple(\n 'my_data_view', 'my_username', 'my_password'\n)\n\n# keep a copy of the session ID (needed to log out)\nsession_id = login_response.session_id\n# update the configuration with your credentials\nconfig.api_key={'Authorization': login_response.access_token}\nconfig.api_key_prefix={'Authorization': 'Bearer'}\n```\n\nSince the `config` object updated here is the configuration object for `api_client`,\nthe latter will now be authorised to access the API.\n\n### Retrieving data from an endpoint\n\nThis code retrieves a list of tables in the `Holidays` system on the given DataView:\n\n```python\ntables = aa.FastStatsSystemsApi(api_client).fast_stats_systems_get_fast_stats_tables(\n 'my_data_view',\n 'holidays'\n)\nprint(f\"There are {tables.count} tables in the Holidays system:\")\nprint('\\n'.join(t.name for t in tables.list))\n```\n\n**Output:**\n\n```commandline\nThere are 9 tables in the Holidays system:\nHouseholds\nPeople\nBookings\nCommunication Responsible\nInsurance\nCommunications\nContent\nResponses Attributed\nJourney History\n```\n\n### Logging out\n\nYou can end your session using the `logout_session` endpoint,\nand passing in the session ID returned from the logging in process above:\n\n```python\naa.SessionsApi(api_client).sessions_logout_session('my_data_view', session_id)\n\ntry:\n tables = aa.FastStatsSystemsApi(api_client).fast_stats_systems_get_fast_stats_tables(\n 'my_data_view',\n 'holidays'\n )\nexcept aa.ApiException as e:\n print(f\"{e.status}: {e.reason}\")\n```\n\n**Output:**\n\n```commandline\n401: Unauthorized\n```\n\nThe first line successfully ended the session and so, as expected,\nthe attempt to retrieve the tables data failed and raised an exception.\n\nNote that logging out like this ends the session on the server-side,\nbut it doesn't remove the copy of the (now invalid) access token kept in the\n`api_client.configuration` object.\n\n\n## General use of the API client\n\nEvery section of the API (`Audiences`, `FastStatsSystems`, `Queries`, `Sessions`, etc)\nhas a corresponding controller class in the `apteco-api` package, named `<section>Api`\ne.g. `SessionsApi`, as seen above.\n\nTo use endpoints from a given section,\ncreate an instance of the controller by passing an \\[authorised\\] `ApiClient` object\nas the single argument to its constructor:\n\n```python\nqueries_controller = aa.QueriesApi(api_client)\n```\n\nThis object then has a method corresponding to each endpoint of that section of the API,\nwhich can be called as a normal Python function.\n\n```python\nquery_result = queries_controller.queries_perform_query_file_count_synchronously(\n 'my_data_view',\n 'holidays',\n query_file=aa.QueryFile('Private/Bookings to France or Germany.xml')\n)\n```\n\nSome of the parameters for this function may need to be specific object types;\nin the example here, the first two parameters are strings specifying the DataView and FastStats system to use for the query,\nwhile the path of the file for the query is given via a `QueryFile` object supplied as a keyword-only argument.\nThe `QueryFile` object itself is initialised with a single argument, namely the filepath.\n\nSimilarly, the function call returns a Python object.\nThese API functions often return 'result' objects which bundle together various data and metadata as attributes,\nand these attributes can then be accessed to obtain the information of interest.\n\n```python\ncount = query_result.counts[0]\nprint(f\"The query matched {count.count_value:,} {count.table_name.lower()}.\")\n```\n\n**Output:**\n\n```commandline\nThe query matched 985,734 bookings.\n```\n\n### Further details\n\nAll classes and methods have detailed docstrings providing further information about their parameters and return values.\n\nYou can also explore the API in a visual way by going to `/swagger/ui/index.html` from your API base URL,\ne.g. `https://example.com/OrbitAPI/swagger/ui/index.html`\n\nHere, each section of the API is listed, and clicking on one will expand the view\nto show all the endpoints that belong to it.\nClicking on an endpoint will similarly expand that to detail its parameters\nand show example values for using it.\nYou can also try out endpoints directly within the interface,\nand view the returned data.\n\n## Author\n\nApteco Ltd\n\nsupport@apteco.com\n\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Apteco API",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://www.apteco.com/"
},
"split_keywords": [
"apteco",
"apteco api",
"apteco marketing suite",
"apteco faststats",
"faststats",
"apteco orbit",
"orbit",
"openapi",
"openapi-generator",
"swagger",
"swagger api",
"api",
"rest"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7bd27a1664d8ea88489d36d3f1c1b478381af61ec7fbe0ef66cfc5317832902c",
"md5": "de86a7977358f192d693b44534e329a2",
"sha256": "7eb1b4490d370d7b85a34332314c304216fbc1ae08f90c0cdc622b9d06dcbec6"
},
"downloads": -1,
"filename": "apteco_api-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "de86a7977358f192d693b44534e329a2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 705172,
"upload_time": "2023-07-14T11:46:44",
"upload_time_iso_8601": "2023-07-14T11:46:44.848084Z",
"url": "https://files.pythonhosted.org/packages/7b/d2/7a1664d8ea88489d36d3f1c1b478381af61ec7fbe0ef66cfc5317832902c/apteco_api-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "71735cdbcd9ba88a82555c4a5fc501ae8d250cd326b2b26b66b03f1198dce1f7",
"md5": "7e7d58e43fa4fc79ef286d6d3465862b",
"sha256": "68dd5a2bc69b05bd3a91957ef5f2136c89300fd1c08eeae8d93ada5c2c5a4690"
},
"downloads": -1,
"filename": "apteco-api-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "7e7d58e43fa4fc79ef286d6d3465862b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 266301,
"upload_time": "2023-07-14T11:46:46",
"upload_time_iso_8601": "2023-07-14T11:46:46.931414Z",
"url": "https://files.pythonhosted.org/packages/71/73/5cdbcd9ba88a82555c4a5fc501ae8d250cd326b2b26b66b03f1198dce1f7/apteco-api-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-14 11:46:46",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "apteco-api"
}
JSON