Analytics API

[perrygeo]

Still in preview and available only for premium and enterprise plans: https://www.mapbox.com/api-documentation/#analytics

[amishas157]

As per discussion w/ @perrygeo and @batpad , I would like to take work on sdk-py for Analytics API ahead. Based on reading through existing sdk-py, found the workflow as following:

• A session is created initially using the Mapbox access token. The existing session is used if there is cache present.
• The next action is to validate all the input parameters.
• Once these are validated, the request is made to the host api.mapbox.com passing the input parameters. And the response is sent back to the client.

Analytics API provides usage statistics for different services provided by Mapbox. It receives parameters as following:

• resourceType : The resource being requested. This can be validated against a list of valid resource types : accounts , tokens , tilesets or styles
• username : The user to whom resource belongs.
• id (optional) : The id for the resource(token id, mapId, styleId respectively). In the case of accounts this isn't required. This will be in form of a string. To validate this parameter, should it checked for a string?
• period (optional) : 2 comma separated dates as ISO formatted strings . This should be validated for ISO formatted strings, first date earlier than second date, difference between two dates should be less than a year.

Note : A secret access token is required which has a scope of analytics::read to create the session.

Response: This returns timestamps, period and different services in form of JSON. Services and usage report depend on the resource type one request for.

• Account : It returns the usage report of different services accessed across all the tokens belonging to user.
• tokens : It returns the usage report of different services accessed using the token id provided.
• tilesets : It returns the usage report of a Map with given MapId in different services
• styleId: It returns the usage report of style with a given StyleId in different services.

I have a general query that if the input parameters need to be validated at SDK end as well, in case when they are getting validated at API level? For example, As I mentioned Period validation above, if we give wrong parameter to API, the response will contain error which we can directly pass to the client back. Or what are the right practices?

@perrygeo @batpad Let me know if I missed out on something or misunderstood something. Would be glad to hear your thoughts on above.

[batpad]

I have a general query that if the input parameters need to be validated at SDK end as well, in case when they are getting validated at API level?

From looking at the other services, @amishas157, it seems like we would want to do basic validation in the SDK before sending the request to the API. I'd follow a similar pattern to the other services, eg: https://github.com/mapbox/mapbox-sdk-py/blob/master/mapbox/services/directions.py#L21

There does seem to be a catch-all for errors returned from the back-end service: https://github.com/mapbox/mapbox-sdk-py/blob/master/mapbox/services/base.py#L68, but from my understanding, it should only fallback to this if there is some problem with the service (eg. a service outage), OR if there are parameters that we have no way of validating on the client-side (i.e. it requires some checking with a back-end data-store or so, for eg. whether a supplied valid looking token is actually valid). For basic input validation of formats and data-types, this should be handled by the SDK before making the request.

Hope my understanding here was correct.

It's possible it might be helpful to write a README first to outline how you see the interface working in the SDK: https://github.com/mapbox/mapbox-sdk-py/tree/master/docs and make sure everyone is on the same page.

[perrygeo]

@amishas157 Fantastic! Thanks for the summary, we're on the right track.

I have a general query that if the input parameters need to be validated at SDK end as well, in case when they are getting validated at API level?

do basic validation in the SDK before sending the request to the API.

👍 There was some discussion early on about where the validation should happen (CLI, SDK or just rely on the API response). The conclusion was that the SDK should be responsible for basic validation of parameters wherever possible; in other words the SDK should catch any obvious input errors and raise an appropriate exception before hitting the API.

A secret access token is required which has a scope of analytics::read to create the session

Errors such as passing a token without the proper scope cannot be handled on the SDK side. For that, we make the request and check the status code of the response. The upload error handling provides an example.

it might be helpful to write a README first

💯 That's a great idea. The markdown examples in our /docs directory are written in Python doctest style (notably with the preceding >>>) in order to automatically test them. We don't necessarily need to do that immediately but it might be helpful if you work well with test-driven development.

For example, to test the static API docs:

$ py.test --doctest-glob='*.md' docs/static.md
============================================== test session starts ==============================================
platform darwin -- Python 3.5.2, pytest-3.0.2, py-1.4.31, pluggy-0.3.1
rootdir: /Users/mperry/work/mapbox-sdk-py, inifile: pytest.ini
plugins: xdist-1.15.0, mypy-0.2.0, ipdb-0.1.dev2, flake8-0.8.1, cov-2.3.1, hypothesis-3.5.2
collected 1 items

docs/static.md .

=========================================== 1 passed in 2.86 seconds ============================================

These tests (unlike our unit tests) hit the live API endpoint and thus provide a pretty good real world integration test to demonstrate code usage.

[sgillies]

@amishas157 very grateful for your help 😃

[amishas157]

Thanks a lot @batpad @perrygeo @sgillies . This was really heplful.

It's possible it might be helpful to write a README first to outline how you see the interface working in the SDK: https://github.com/mapbox/mapbox-sdk-py/tree/master/docs and make sure everyone is on the same page.

Seems like a great idea. Coming with it soon.

[perrygeo]

@amishas157 and @sgillies finished this work in #161 🎉