cartodb4/dataservices-api
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Reorder dev center folder

Browse Source
This commit is contained in:
csubira
2019-03-01 11:53:49 +01:00
parent 2ae1547f3c
commit f1e4ff6f33
19 changed files with 2 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/developer-center/support/01-support-options.md Normal file
View File

@@ -0,0 +1,36 @@
## Support Options
Feeling stuck? There are many ways to find help.
* Ask a question on [GIS StackExchange](https://gis.stackexchange.com/questions/tagged/carto) using the `CARTO` tag.
* [Report an issue](https://github.com/CartoDB/cartodb/issues) in Github.
* Engine Plan customers have additional access to enterprise-level support through CARTO's support representatives.
If you just want to describe an issue or share an idea, just <a class="typeform-share" href="https://cartohq.typeform.com/to/mH6RRl" data-mode="popup" target="_blank"> send your feedback</a>
### Issues on Github
If you think you may have found a bug, or if you have a feature request that you would like to share with the Data Services API team, please [open an issue](https://github.com/CartoDB/cartodb/issues/new).
Before opening an issue, review the [contributing guidelines](https://github.com/CartoDB/cartodb/blob/master/CONTRIBUTING.md).
### Community support on GIS Stack Exchange
GIS Stack Exchange is the most popular community in the geospatial industry. This is a collaboratively-edited question and answer site for geospatial programmers and technicians. It is a fantastic resource for asking technical questions about developing and maintaining your application.
When posting a new question, please consider the following:
* Read the GIS Stack Exchange [help](https://gis.stackexchange.com/help) and [how to ask](https://gis.stackexchange.com/help/how-to-ask) pages for guidelines and tips about posting questions.
* Be very clear about your question in the subject. A clear explanation helps those trying to answer your question, as well as those who may be looking for information in the future.
* Be informative in your post. Details, code snippets, logs, screenshots, etc. help others to understand your problem.
* Use code that demonstrates the problem. It is very hard to debug errors without sample code to reproduce the problem.
### Engine Plan Customers
Engine Plan customers have additional support options beyond general community support. As per your account Terms of Service, you have access to enterprise-level support through CARTO's support representatives available at [enterprise-support@carto.com](mailto:enterprise-support@carto.com)
In order to speed up the resolution of your issue, provide as much information as possible (even if it is a link from community support). This allows our engineers to investigate your problem as soon as possible.
If you are not yet CARTO customer, browse our [plans & pricing](https://carto.com/pricing/) and find the right plan for you.

36
docs/developer-center/support/02-contribute.md Normal file
View File

@@ -0,0 +1,36 @@
## Contribute
CARTO platform is an open-source ecosystem. You can read about the [fundamentals]({{site.fundamental_docs}}/components/) of CARTO architecture and its components.
We are more than happy to receive your contributions to the code and the documentation as well.
## Filling a ticket
If you want to open a new issue in our repository, please follow these instructions:
1. Descriptive title.
2. Write a good description, it always helps.
3. Specify the steps to reproduce the problem.
4. Try to add an example showing the problem.
## Contributing code
Best part of open source, collaborate in Data Services API code!. We like hearing from you, so if you have any bug fixed, or a new feature ready to be merged, those are the steps you should follow:
1. Fork the repository.
2. Create a new branch in your forked repository.
3. Commit your changes. Add new tests if it is necessary.
4. Open a pull request.
5. Any of the maintainers will take a look.
6. If everything works, it will merged and released \o/.
If you want more detailed information, this [GitHub guide](https://guides.github.com/activities/contributing-to-open-source/) is a must.
## Completing documentation
Data Services API documentation is located in ```docs/```. That folder is the content that appears in the [Developer Center](http://carto.com/developers/data-services-api/). Just follow the instructions described in [contributing code](#contributing-code) and after accepting your pull request, we will make it appear online :).
**Tip:** A convenient, easy way of proposing changes in documentation is by using the GitHub editor directly on the web. You can easily create a branch with your changes and make a PR from there.
## Submitting contributions
You will need to sign a Contributor License Agreement (CLA) before making a submission. [Learn more here](https://carto.com/contributions).

135
docs/developer-center/support/03-quota-information.md Normal file
View File

@@ -0,0 +1,135 @@
## Quota Information
**Based on your account plan, some of the Data Services API functions are subject to quota limitations and extra fees may apply.** View our [terms and conditions](https://carto.com/terms/), or [contact us](mailto:sales@carto.com) for details about which functions require service credits to your account.
### Quota Consumption
Quota consumption is calculated based on the number of request made for each function. Be mindful of the following usage recommendations when using the Data Services API functions:
* One credit per function call will be consumed. The results are not cached. If the query is applied to a _N_ rows dataset, then _N_ credits are consumed
* Avoid running dynamic queries to these functions in your maps. This can result in credit consumption per map view.
**Note:** Queries to the Data Services API, and any of its functions in your maps, may be forbidden in the future
* It is advised to store results of these queries into your datasets, and refresh them as needed. This ensure more control of quota credits for your account
### Quota Information Functions
There are several SQL functions that you can run to obtain quota information about your services.
### cdb_service_quota_info()
Returns information about per-service quotas (available and used) for the account.
##### Returns
This function returns a set of service quota information records, one per service.
Name | Type | Description
--------------- | --------- | ------------
`service` | `text` | Type of service.
`monthly_quota` | `numeric` | Quota available to the user (number of calls) per monthly period.
`used_quota` | `numeric` | Quota used by the user in the present period.
`soft_limit` | `boolean` | Set to `True`, if the user has *soft-limit* quota.
`provider` | `text` | Service provider for this type of service.
Service Types:
* `'isolines'` [Isoline/Isochrones (isochrone/isodistance lines) service](https://carto.com/docs/carto-engine/dataservices-api/isoline_functions/)
* `'hires_geocoder'` [Street level geocoding](https://carto.com/docs/carto-engine/dataservices-api/geocoding-functions#street-level-geocoder)
* `'routing'` [Routing functions](https://carto.com/docs/carto-engine/dataservices-api/routing_functions/)
* `'observatory'` Data Observatory services ([demographic](https://carto.com/docs/carto-engine/dataservices-api/demographic_functions/) and [segmentation](https://carto.com/docs/carto-engine/dataservices-api/segmentation_functions/) functions)
**Notes**
Users who have *soft-quota* activated never run out of quota, but they may incur extra
expenses when the regular quota is exceeded.
A zero value of `monthly_quota` indicates that the service has not been activated for the user.
##### Example
```sql
SELECT * FROM cdb_service_quota_info();
```
Result:
```sql
service | monthly_quota | used_quota | soft_limit | provider
----------------+---------------+------------+------------+------------------
isolines | 100 | 0 | f | tomtom
hires_geocoder | 100 | 0 | f | tomtom
routing | 50 | 0 | f | tomtom
observatory | 0 | 0 | f | data observatory
(4 rows)
```
In this case, notice that the user has no access to the observatory services. All quotas are *hard-limited* (no soft limits), and no quota has been used in the present period.
### cdb_enough_quota(service text ,input_size numeric)
This function is useful to check if enough quota is available for completing a job.
This is specifically relevant if a number of service calls are to be performed inside a transaction. If any of the calls fails (due to exceeded quota), the transaction will be rolled back; resulting in partial quota consumption, but no saved results from the services consumed.
**Tip:** If you are requesting repeating quota-consuming functions (e.g. to geocode a whole table), it is extremely important to check if enough quota is available to complete the job _before_ applying this function.
Note that some services consume more than one credit per row/call. For example, isolines (with more than one range/track) consume (N rows x M ranges) credits; indicating that the input size should be N x M.
##### Arguments
Name | Type | Description
------------ | --------- | -----------
`service` | `text` | Service to check; see the list of valid services above.
`input_size` | `numeric` | Number of service calls required, i.e. size of the input to be processed.
##### Returns
The result is a *boolean* value. A *true* value (`'t'`) indicates that the available quota
for the service is enough for the input size requested. A *false* value (`'f'`) indicates
insufficient quota.
##### Example
Suppose you want to geocode a whole table. In order to check that you have enough quota, and avoid a "quota exhausted" exception, first find out how many records you need to geocode:
```sql
SELECT COUNT(*) FROM {tablename} WHERE {street_name_column} IS NOT NULL;
```
Result: A sample result of 10000 records:
```sql
count
-------
10000
(1 row)
```
The result shows how much quota is needed to complete this job. In this case,
each call to `cdb_geocode_street_point` consumes one quota credit. This indicates that we need one credit per row to geocode the whole table.
```sql
SELECT cdb_enough_quota('hires_geocoder', {number_of_records});
```
The result is similar to the following:
```sql
cdb_enough_quota
------------------
t
```
If the result of this query is *true* (`'t'`), you can safely proceed. If a *false* value (`'f'`) is returned, you should avoid processing any more requests that consume quota. Apply the `cdb_service_quota_info` function to get more information about your services.
**Note:** Remember to apply any filtering conditions that you used to count the records (in this case, `{street_name_column} IS NOT NULL`):
```sql
UPDATE {tablename} SET the_geom = cdb_geocode_street_point({street_name_column})
WHERE {street_name_column} IS NOT NULL;
```

197
docs/developer-center/support/04-rate-limits.md Normal file
View File

@@ -0,0 +1,197 @@
## Rate limits
Services can be rate-limited. (currently only gecoding is limited)
The rate limits configuration can be established at server, organization or user levels, the latter having precedence over the earlier.
The default configuration (a null or empty configuration) doesn't impose any limits.
The configuration consist of a JSON object with two attributes:
* `period`: the rate-limiting period, in seconds.
* `limit`: the maximum number of request in the established period.
If a service request exceeds the configured rate limits
(i.e. if more than `limit` calls are performe in a fixed interval of
duration `period` seconds) the call will fail with an "Rate limit exceeded" error.
### Server-side interface
There's a server-side SQL interface to query or change the configuration.
#### cdb_dataservices_server.cdb_service_get_rate_limit(username, orgname, service)
This function returns the rate limit configuration for a given user and service.
##### Returns
The result is a JSON object with the configuration (`period` and `limit` attributes as explained above).
#### cdb_dataservices_server.cdb_service_set_user_rate_limit(username, orgname, service, rate_limit)
This function sets the rate limit configuration for the user. This overrides any other configuration.
The configuration is provided as a JSON literal. To remove the user-level configuration `NULL` should be passed as the `rate_limit`.
##### Returns
This functions doesn't return any value.
#### cdb_dataservices_server.cdb_service_set_org_rate_limit(username, orgname, service, rate_limit)
This function sets the rate limit configuration for the organization.
This overrides server level configuration and is overriden by user configuration if present.
The configuration is provided as a JSON literal. To remove the organization-level configuration `NULL` should be passed as the `rate_limit`.
##### Returns
This functions doesn't return any value.
#### cdb_dataservices_server.cdb_service_set_server_rate_limit(username, orgname, service, rate_limit)
This function sets the default rate limit configuration for all users accesing the dataservices server. This is overriden by organization of user configuration.
The configuration is provided as a JSON literal. To remove the organization-level configuration `NULL` should be passed as the `rate_limit`.
##### Returns
This functions doesn't return any value.
### Client-side interface
For convenience there's also a client-side interface (in the client dataservices-api extension), consisting
of public functions to get the current configuration and privileged functions to change it.
#### Public functions
These functions are accesible to non-privileged roles, and should only be executed
using the role corresponding to a CARTO user, since that will determine the
user and organization to which the rate limits configuration applies.
#### cdb_dataservices_client.cdb_service_get_rate_limit(service)
This function returns the rate limit configuration in effect for the specified service
and the user corresponding to the role which makes the calls. The effective configuration
may come from any of the configuration levels (server/organization/user); only the
existing configuration with most precedence is returned.
##### Returns
The result is a JSON object with the configuration (`period` and `limit` attributes as explained above).
##### Example:
```
SELECT cdb_dataservices_client.cdb_service_get_rate_limit('geocoder');
cdb_service_get_rate_limit
---------------------------------
{"limit": 1000, "period": 86400}
(1 row)
```
#### Privileged (superuser) functions
Thes functions are not accessible by regular user roles, and the user and organization names must be provided as parameters.
#### cdb_dataservices_client.cdb_service_set_user_rate_limit(username, orgname, service, rate_limit)
This function sets the rate limit configuration for the user. This overrides any other configuration.
The configuration is provided as a JSON literal. To remove the user-level configuration `NULL` should be passed as the `rate_limit`.
##### Returns
This functions doesn't return any value.
##### Example
This will configure the geocoder service rate limit for user `myusername`, a non-organization user.
The limit will be set at 1000 requests per day. Since the user doesn't belong to any organization,
`NULL` will be passed to the organization argument; otherwise the name of the user's organization should
be provided.
Note that the name of the geocoding services is `geocoder` and not `geocoding`.
```
SELECT cdb_dataservices_client.cdb_service_set_user_rate_limit(
'myusername',
NULL,
'geocoder',
'{"limit":1000,"period":86400}'
);
cdb_service_set_user_rate_limit
---------------------------------
(1 row)
```
#### cdb_dataservices_client.cdb_service_set_org_rate_limit(username, orgname, service, rate_limit)
This function sets the rate limit configuration for the organization.
This overrides server level configuration and is overriden by user configuration if present.
The configuration is provided as a JSON literal. To remove the organization-level configuration `NULL` should be passed as the `rate_limit`.
##### Returns
This functions doesn't return any value.
##### Example
This will configure the geocoder service rate limit for the `myorg` organization.
The limit will be set at 100 requests per hour.
Note that even we're setting the default configuration for the whole organization,
the name of a user of the organization must be provided for technical reasons.
```
SELECT cdb_dataservices_client.cdb_service_set_org_rate_limit(
'myorgadmin',
'myorg',
'geocoder',
'{"limit":100,"period":3600}'
);
cdb_service_set_org_rate_limit
---------------------------------
(1 row)
```
#### cdb_dataservices_client.cdb_service_set_server_rate_limit(username, orgname, service, rate_limit)
This function sets the default rate limit configuration for all users accesing the dataservices server. This is overriden by organization of user configuration.
The configuration is provided as a JSON literal. To remove the organization-level configuration `NULL` should be passed as the `rate_limit`.
##### Returns
This functions doesn't return any value.
##### Example
This will configure the default geocoder service rate limit for all users
accesing the data-services server.
The limit will be set at 10000 requests per month.
Note that even we're setting the default configuration for the server,
the name of a user and the name of the corresponding organization (or NULL)
must be provided for technical reasons.
```
SELECT cdb_dataservices_client.cdb_service_set_server_rate_limit(
'myorgadmin',
'myorg',
'geocoder',
'{"limit":10000,"period":108000}'
);
cdb_service_set_server_rate_limit
---------------------------------
(1 row)
```