From eb6fe79a4c37f3b4bdbf6e1ec1fe40daec7a568a Mon Sep 17 00:00:00 2001 From: Mario de Frutos Date: Tue, 17 May 2016 15:55:57 +0200 Subject: [PATCH 1/7] Document about how quota management works --- doc/internal/quota_management.md | 57 ++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 doc/internal/quota_management.md diff --git a/doc/internal/quota_management.md b/doc/internal/quota_management.md new file mode 100644 index 0000000..a48ee23 --- /dev/null +++ b/doc/internal/quota_management.md @@ -0,0 +1,57 @@ +All the services from Dataservices API are subject to quota management: check, limit, etc. + +There are three main fields in the quota management: + +- **Quota**: Number of requests of this kind the user could make, eg. Number of street geocoding requests +- **Soft limit**: This flag enables the user to surpass his/her assigned quota. When this flag is activated, there is no quota check so the user could make all the resquests that he/she wants. +- **Block price**: Price for every 1000 requests + + +All the user/organization quota information is stored in the user metadata in Redis but managed by the CartoDB Rails app through its models. Nevertheless you could change/read the redis information through the following keys: + +- hgetall rails:users:username +- hgetall rails:orgs:orgname + +This whole information is managed by the CartoDB Rails App too so we could make a numer of useful operations in order to know how many quota do you have, how many quota have you spent this month and so on: + +- How can I know the current quota, number of uses, etc for a user? + +> You could use the following endpoint to know it: https://.cartodb.com/api/v1/users/?api_key= +> In the result of this endpoint you can see blocks with all the information. Eg: +``` +"geocoding": { + "quota": 1000, + "block_price": 1500, + "monthly_use": 743, + "hard_limit": true +} +``` + +- How can I set a new quota for a user: + +> This operation could be done through the rails console: + - First you have to connect to the rails console: `bundle exec rails c` + - One in the console you have to get the target user/organization: + - `u = User.find(username: '')` + - `o = Organization.find(name: '')` + - After we have the user/organization, we could change the quota or the hard limit flag for the desired service. I'm going to use geoding as an example but it could be done with all the services : + - ``` + u.geocoding_quota = 2000 + [u.soft_geocoding_limit = true|false] + u.save + ``` + - ``` + o.geocoding_quota = 2000 + o.save + ``` + - This way the user now has 2000 request as his/her current quota + - We can only change the hard limit flag for users not for organizations + +- What services we could change?: + +The following list numbers all the current services but this is a living list so it could keep growing in the future: + + - Geocoding: `geocoding_quota`, `soft_geocoding_limit` + - Isolines: `here_isolines_quota`, `soft_here_isolines_limit` + - Data observatory snapshot: `obs_snapshot_quota`, `soft_obs_snapshot_limit` + - Data observatory general: `obs_general_quota`, `soft_obs_general_limit` \ No newline at end of file From 8a8a5e11b517436d25b896c4af21922bb13d2ba0 Mon Sep 17 00:00:00 2001 From: Carla Date: Tue, 17 May 2016 16:05:47 +0200 Subject: [PATCH 2/7] Update quota_management.md --- doc/internal/quota_management.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/internal/quota_management.md b/doc/internal/quota_management.md index a48ee23..1132052 100644 --- a/doc/internal/quota_management.md +++ b/doc/internal/quota_management.md @@ -3,22 +3,22 @@ All the services from Dataservices API are subject to quota management: check, l There are three main fields in the quota management: - **Quota**: Number of requests of this kind the user could make, eg. Number of street geocoding requests -- **Soft limit**: This flag enables the user to surpass his/her assigned quota. When this flag is activated, there is no quota check so the user could make all the resquests that he/she wants. +- **Soft limit**: This flag enables the user to surpass their assigned quota. When this flag is activated, there is no quota check so the user could make all the requests that they want. - **Block price**: Price for every 1000 requests -All the user/organization quota information is stored in the user metadata in Redis but managed by the CartoDB Rails app through its models. Nevertheless you could change/read the redis information through the following keys: +All the user/organization quota information is stored in the user metadata in Redis but managed by the CartoDB Rails app through the User/Organization models. Nevertheless you could change/read the Redis information through the following keys: -- hgetall rails:users:username -- hgetall rails:orgs:orgname +- `hgetall rails:users:username` +- `hgetall rails:orgs:orgname` -This whole information is managed by the CartoDB Rails App too so we could make a numer of useful operations in order to know how many quota do you have, how many quota have you spent this month and so on: +This whole information is managed by the CartoDB Rails App too so we could make a number of useful operations in order to know how many quota do you have, how many quota have you spent this month, and so on: - How can I know the current quota, number of uses, etc for a user? -> You could use the following endpoint to know it: https://.cartodb.com/api/v1/users/?api_key= -> In the result of this endpoint you can see blocks with all the information. Eg: -``` + You could use the following endpoint to know it: `https://.cartodb.com/api/v1/users/?api_key=` + In the result of this endpoint you can see blocks with all the information. Eg: + ```json "geocoding": { "quota": 1000, "block_price": 1500, @@ -29,12 +29,12 @@ This whole information is managed by the CartoDB Rails App too so we could make - How can I set a new quota for a user: -> This operation could be done through the rails console: + This operation could be done through the rails console: - First you have to connect to the rails console: `bundle exec rails c` - - One in the console you have to get the target user/organization: + - Once in the console you have to get the target user/organization: - `u = User.find(username: '')` - `o = Organization.find(name: '')` - - After we have the user/organization, we could change the quota or the hard limit flag for the desired service. I'm going to use geoding as an example but it could be done with all the services : + - After we have the user/organization, we could change the quota or the hard limit flag for the desired service. I'm going to use geocoding as an example but it could be done with all the services: - ``` u.geocoding_quota = 2000 [u.soft_geocoding_limit = true|false] @@ -44,14 +44,14 @@ This whole information is managed by the CartoDB Rails App too so we could make o.geocoding_quota = 2000 o.save ``` - - This way the user now has 2000 request as his/her current quota - - We can only change the hard limit flag for users not for organizations + - This way the user now has 2000 requests as their current quota + - We can only change the hard limit flag for users, not for organizations -- What services we could change?: +- What services could we edit?: -The following list numbers all the current services but this is a living list so it could keep growing in the future: + The following list numbers all the current services but this is a living list so it could keep growing in the future: - Geocoding: `geocoding_quota`, `soft_geocoding_limit` - Isolines: `here_isolines_quota`, `soft_here_isolines_limit` - Data observatory snapshot: `obs_snapshot_quota`, `soft_obs_snapshot_limit` - - Data observatory general: `obs_general_quota`, `soft_obs_general_limit` \ No newline at end of file + - Data observatory general: `obs_general_quota`, `soft_obs_general_limit` From 8df879f7d3d8cbbc4a2403323df94923416d68d9 Mon Sep 17 00:00:00 2001 From: Carla Date: Tue, 17 May 2016 16:09:09 +0200 Subject: [PATCH 3/7] Add remaining credits left calculation tip --- doc/internal/quota_management.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/internal/quota_management.md b/doc/internal/quota_management.md index 1132052..e92f172 100644 --- a/doc/internal/quota_management.md +++ b/doc/internal/quota_management.md @@ -27,6 +27,8 @@ This whole information is managed by the CartoDB Rails App too so we could make } ``` + Note: the remaining credits left can be computed as: `remaining_quota = quota - monthly_use`. + - How can I set a new quota for a user: This operation could be done through the rails console: From 4730088a227c68f51e419f7373a3b9f6e8204c9a Mon Sep 17 00:00:00 2001 From: Carla Date: Tue, 17 May 2016 16:11:58 +0200 Subject: [PATCH 4/7] Update quota_management.md --- doc/internal/quota_management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/internal/quota_management.md b/doc/internal/quota_management.md index e92f172..860c461 100644 --- a/doc/internal/quota_management.md +++ b/doc/internal/quota_management.md @@ -3,7 +3,7 @@ All the services from Dataservices API are subject to quota management: check, l There are three main fields in the quota management: - **Quota**: Number of requests of this kind the user could make, eg. Number of street geocoding requests -- **Soft limit**: This flag enables the user to surpass their assigned quota. When this flag is activated, there is no quota check so the user could make all the requests that they want. +- **Soft limit**: This flag enables the user to surpass their assigned quota. When this flag is activated, there is no quota check so the user could make all the requests that they want. Consequently, the `hard_limit` flag, when enabled, indicates that the user cannot surpass the assigned quota. - **Block price**: Price for every 1000 requests From fedcd606c5a11fa14e6a4d3e7b12a062debee955 Mon Sep 17 00:00:00 2001 From: Carla Date: Tue, 17 May 2016 16:14:01 +0200 Subject: [PATCH 5/7] add street level clarification for geocoding --- doc/internal/quota_management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/internal/quota_management.md b/doc/internal/quota_management.md index 860c461..bed0ef0 100644 --- a/doc/internal/quota_management.md +++ b/doc/internal/quota_management.md @@ -53,7 +53,7 @@ This whole information is managed by the CartoDB Rails App too so we could make The following list numbers all the current services but this is a living list so it could keep growing in the future: - - Geocoding: `geocoding_quota`, `soft_geocoding_limit` + - Geocoding (street level): `geocoding_quota`, `soft_geocoding_limit` - Isolines: `here_isolines_quota`, `soft_here_isolines_limit` - Data observatory snapshot: `obs_snapshot_quota`, `soft_obs_snapshot_limit` - Data observatory general: `obs_general_quota`, `soft_obs_general_limit` From 6abc5a4cddb123f3285e1512588960b204d59c02 Mon Sep 17 00:00:00 2001 From: Mario de Frutos Date: Tue, 17 May 2016 16:35:41 +0200 Subject: [PATCH 6/7] Added section how the quota is spent in the document --- doc/internal/quota_management.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/doc/internal/quota_management.md b/doc/internal/quota_management.md index bed0ef0..f1f463d 100644 --- a/doc/internal/quota_management.md +++ b/doc/internal/quota_management.md @@ -12,13 +12,13 @@ All the user/organization quota information is stored in the user metadata in Re - `hgetall rails:users:username` - `hgetall rails:orgs:orgname` -This whole information is managed by the CartoDB Rails App too so we could make a number of useful operations in order to know how many quota do you have, how many quota have you spent this month, and so on: +This whole information is managed by the CartoDB Rails App too so we could make a numer of useful operations in order to know how much quota do you have, how much quota have you spent this month and so on. -- How can I know the current quota, number of uses, etc for a user? +###How can I know the current quota, number of uses, etc for a user?### - You could use the following endpoint to know it: `https://.cartodb.com/api/v1/users/?api_key=` - In the result of this endpoint you can see blocks with all the information. Eg: - ```json +You could use the following endpoint to know it: https://.cartodb.com/api/v1/users/?api_key= +In the result of this endpoint you can see blocks with all the information. Eg: +``` "geocoding": { "quota": 1000, "block_price": 1500, @@ -27,11 +27,9 @@ This whole information is managed by the CartoDB Rails App too so we could make } ``` - Note: the remaining credits left can be computed as: `remaining_quota = quota - monthly_use`. +### How can I set a new quota for a user### -- How can I set a new quota for a user: - - This operation could be done through the rails console: +This operation could be done through the rails console: - First you have to connect to the rails console: `bundle exec rails c` - Once in the console you have to get the target user/organization: - `u = User.find(username: '')` @@ -49,7 +47,7 @@ This whole information is managed by the CartoDB Rails App too so we could make - This way the user now has 2000 requests as their current quota - We can only change the hard limit flag for users, not for organizations -- What services could we edit?: +### What services we could change?### The following list numbers all the current services but this is a living list so it could keep growing in the future: @@ -57,3 +55,9 @@ This whole information is managed by the CartoDB Rails App too so we could make - Isolines: `here_isolines_quota`, `soft_here_isolines_limit` - Data observatory snapshot: `obs_snapshot_quota`, `soft_obs_snapshot_limit` - Data observatory general: `obs_general_quota`, `soft_obs_general_limit` + +### How is the quota spent?### + +Almost in all the services: geocoding, data observatory snapshot and general the number of spent credits is calculated per request made (either successful or empty request). + +In the case of the isolines service, the number of credits is calculated based on the number of isolines generated by the request. Ie. If your query generates 3 isolines for the request, you've spent 3 isolines credits. From 3d617a4349457f68033857d9d2ee8a3d66415636 Mon Sep 17 00:00:00 2001 From: Mario de Frutos Date: Tue, 17 May 2016 16:47:50 +0200 Subject: [PATCH 7/7] Fixed markdown syntax --- doc/internal/quota_management.md | 45 +++++++++++++++++--------------- 1 file changed, 24 insertions(+), 21 deletions(-) diff --git a/doc/internal/quota_management.md b/doc/internal/quota_management.md index f1f463d..7ce35c9 100644 --- a/doc/internal/quota_management.md +++ b/doc/internal/quota_management.md @@ -18,6 +18,7 @@ This whole information is managed by the CartoDB Rails App too so we could make You could use the following endpoint to know it: https://.cartodb.com/api/v1/users/?api_key= In the result of this endpoint you can see blocks with all the information. Eg: + ``` "geocoding": { "quota": 1000, @@ -30,34 +31,36 @@ In the result of this endpoint you can see blocks with all the information. Eg: ### How can I set a new quota for a user### This operation could be done through the rails console: - - First you have to connect to the rails console: `bundle exec rails c` - - Once in the console you have to get the target user/organization: - - `u = User.find(username: '')` - - `o = Organization.find(name: '')` - - After we have the user/organization, we could change the quota or the hard limit flag for the desired service. I'm going to use geocoding as an example but it could be done with all the services: - - ``` - u.geocoding_quota = 2000 - [u.soft_geocoding_limit = true|false] - u.save - ``` - - ``` - o.geocoding_quota = 2000 - o.save - ``` - - This way the user now has 2000 requests as their current quota - - We can only change the hard limit flag for users, not for organizations + +- First you have to connect to the rails console: `bundle exec rails c` +- Once in the console you have to get the target user/organization: + - `u = User.find(username: '')` + - `o = Organization.find(name: '')` +- After we have the user/organization, we could change the quota or the hard limit flag for the desired service. I'm going to use geocoding as an example but it could be done with all the services: + + ``` + u.geocoding_quota = 2000 + [u.soft_geocoding_limit = true|false] + u.save + ``` + ``` + o.geocoding_quota = 2000 + o.save + ``` +- This way the user now has 2000 requests as their current quota +- We can only change the hard limit flag for users, not for organizations ### What services we could change?### The following list numbers all the current services but this is a living list so it could keep growing in the future: - - Geocoding (street level): `geocoding_quota`, `soft_geocoding_limit` - - Isolines: `here_isolines_quota`, `soft_here_isolines_limit` - - Data observatory snapshot: `obs_snapshot_quota`, `soft_obs_snapshot_limit` - - Data observatory general: `obs_general_quota`, `soft_obs_general_limit` + - Geocoding (street level): `geocoding_quota`, `soft_geocoding_limit` + - Isolines: `here_isolines_quota`, `soft_here_isolines_limit` + - Data observatory snapshot: `obs_snapshot_quota`, `soft_obs_snapshot_limit` + - Data observatory general: `obs_general_quota`, `soft_obs_general_limit` ### How is the quota spent?### Almost in all the services: geocoding, data observatory snapshot and general the number of spent credits is calculated per request made (either successful or empty request). -In the case of the isolines service, the number of credits is calculated based on the number of isolines generated by the request. Ie. If your query generates 3 isolines for the request, you've spent 3 isolines credits. +In the case of the isolines service, the number of credits is calculated based on the number of isolines generated by the request. Ie. If your query generates 3 isolines for the request, you've spent 3 isolines credits. \ No newline at end of file