API documentation - 1 -

Transcription

1 API documentation - 1 -

2 Table of Contents 1. Introduction 1.1. What is an API 2. API Functions 2.1. Purge list of files Description Implementation 2.2. Purge of whole cache (all files on all edge servers) Description Implementation 2.3. Prefetch file to edge servers local cache Description Implementation 2.4. Create CDN resource Description Implementation 2.5. Delete CDN resource Description Implementation 2.6. Edit CDN resource Description Implementation 2.7. Fetch statistics data Description Implementation 2.8. Get CDN details Description Implementation - 2 -

3 1. Introduction 1.1. What is an API API is application programming interface and it allows to communicate with CDN77 service through JSON (JavaScript Object Notation). CDN77 API allows you to do various commands and tasks, like creating new CDN resource, editation of CDN resource, purging edge servers local cache and other tasks needed when using CDN77 from external script or server Supported API functions Supported CDN77 s API functions are: Purge of whole edge servers local cache Purge list of file(s) Prefetch content to edge servers local cache CDN resource editation creation details removal Traffic statistics - 3 -

4 2. API Functions 2.1. Purge list of files Description Purge API request is used in case, the invalidation of some files in edge servers local cache is needed. (for instance: when refresh of files in the CDN to new version is needed). It takes from 2 to 10 minutes, until the request for file removal is processed Implementation Following HTTP POST parameters is accepted on the following gateway: POST parameter name Parameter description Example of usage id login ID of CDN resource, on which the content will be purged Login to CDN77 client section 1234 [email protected] passwd API password 8vL4BpXbRqgPTKA0hV36dWjMTNfIk ZK8 json Contains paths of files to be purged Single file: {"purge_paths":"path/to/your/file.jpg"} More files: {"purge_paths":"/path/to/file1.png\n/path/ to/file2.png\n/path/to/otherfile.png"} All parameters are required. Additional notes: - 4 -

5 id of CDN resource can be found in the CDN list: API password can be found in the API section, which can be found in the client section: Limitations of purge API method allowed requests per second: 1 allowed requests per day: 1000 Example of usage (via Linux s curl utility): Purging of single file: curl --data "id=id of cdn&[email protected]&passwd=your api password&json={'purge_paths':'/path/to/file.jpg'}" client.cdn77.com/api/purge Purging of more files at once: curl --data "id=id of cdn&[email protected]&passwd=your api password&json={'purge_paths':'/path/to/file.jpg\n/path/to/ file2.jpg\n/path/to/file3.jpg''}" It returns status : ok JSON response in success and any other response or status is failure. Example of successful purge API response: {"status":"ok","description":"purge request successful"} string(19) "{'purge_paths':'/'}" - 5 -

6 2.2. Purge of whole cache (all files on all edge servers) Description Purge of whole cache API request is used in case, the invalidation of all files in edge servers local cache is needed. (for instance: when refresh of all files in the CDN to new version is needed). It takes from 2 to 10 minutes, until the request for file removal is processed Implementation Following HTTP POST parameters is accepted on the following gateway: POST parameter name Parameter description Example of usage id login ID of CDN resource, on which the content will be purged Login to CDN77 client section 1234 [email protected] passwd API password 8vL4BpXbRqgPTKA0hV36dWjMTNfIkZK8 All parameters are required

7 Additional notes: id of CDN resource can be found in the CDN list: API password can be found in the API section, which can be found in the client section: Limitations of purge all API method allowed requests per second: 1 allowed requests per day: 1000 Example of usage (via Linux s curl utility): curl --data "id=id of cdn&[email protected]&passwd=your api password" It returns status : ok JSON response in success and any other response or status is failure. Example of successful purge all API response: {"status":"ok","description":"purge request successful"} - 7 -

8 2.3. Prefetch file to edge servers local cache Description Prefetch of desired file or files to edge servers local cache is used in case, the predownload of all desired files from origin to edge servers cache is needed. (for instance: when new files are uploaded and it is needed to upload them to edge servers local cache before presenting them to public). There is one advantage of doing this: The CDN cache can be pre-filled, so it will be present there, when presented to public. This practically means, that even the first request from visitor to this new file, will be served from edge servers local cache and so it will be faster, than in case the file is not in the edge servers local cache yet and has to be downloaded from origin at first. It takes from 2 to 10 minutes, until the request for file removal is processed. The whole time of upload to edge servers depends on the connectivity (bandwidth) between the origin and edge server (and on the load on the line of course; in example: it will be faster if there is 1 Gbps network on the origin and on the edge server than in case of 100 Mbps on origin or edge server) Implementation Following HTTP POST parameters is accepted on the following gateway: POST parameter name Parameter description Example of usage - 8 -

9 id login ID of CDN resource, on which the content will be purged Login to CDN77 client section 1234 passwd API password 8vL4BpXbRqgPTKA0hV36dWjMTNfIkZK8 json Contains paths of files to be purged Single file: {"prefetch_paths":"path/to/your/file.jpg"} More files: {"prefetch_paths":"/path/to/file1.png\n/path/to/file2.png\n/path/to/ otherfile.png"} All parameters are required. Additional notes: id of CDN resource can be found in the CDN list: API password can be found in the API section, which can be found in the client section: Limitations of prefetch API method allowed requests per second: 1 allowed requests per day: 1000 Example of usage (via Linux s curl utility): Prefetching of single file: curl --data "id=id of cdn&[email protected]&passwd=your api password&json={'prefetch_paths':'/path/to/file.jpg'}" client.cdn77.com/api/prefetch Prefetching of more files at once: - 9 -

10 curl --data "id=id of api password&json={'prefetch_paths':'/path/to/file.jpg\n/path/to/ file2.jpg\n/path/to/file3.jpg''}" It returns status : ok JSON response in success and any other response or status is failure. Example of successful prefetch API response: {"status":"ok","description":"prefetch request successful"} 2.4. Create CDN resource Description New CDN resource can be created via API just like from the client section. Origin domain, cname and SSL support can be chosen in the creation Implementation Following HTTP POST parameters is accepted on the following gateway: POST parameter name Parameter description Example of usage origin_url cname Origin domain, from which the content will be pulled CNAME for your CDN resource (without protocol specification) cdn.yourwebsite.com (without protocol specification)

11 ssl Type of CDN resource values: 0 = SSL disabled (custom CNAME could be used) 1 = SSL enabled (CNAME must end with r.worldssl.net ) method login Amount of data returned in response Login to CDN77 client section values: verbose = more data will be returned in response without value (not present/not set or null) = simple response without CDN resource ID etc. [email protected] passwd API password 8vL4BpXbRqgPTKA0hV36dWjMTNfIkZK8 All parameters are required, except for method parameter, which is optional. Additional notes: id of CDN resource can be found in the CDN list: API password can be found in the API section, which can be found in the client section: Limitations of prefetch API method allowed requests per second: 1 allowed requests per day: 100 Example of usage (via Linux s curl utility): Creating CDN resource without SSL support: curl --data "[email protected]&passwd=your api password&origin_url= It returns status : ok JSON response in success and any other response or status is failure

12 Example of successful create CDN API response: {"status":"ok","description":"cdn cdn.yourwebsite.com created"} Creating CDN resource without SSL support with method present and with value verbose : curl --data "[email protected]&passwd=your api password&origin_url= It returns status : ok JSON response in success and any other response or status ( status : error ) is failure. Example of successful create CDN API response: {"status":"ok","description":"cdn cdn.yourwebsite.com created","id":1234,"cdnurl":" r.cdn77.net","cname":"cdn.yourwebsite.com"} 2.5. Delete CDN resource Description Any CDN resource can be deleted via API (via its ID) just like from the client section Implementation Following HTTP POST parameters is accepted on the following gateway: POST parameter name Parameter description Example of usage

13 id login ID of CDN resource, on which the Login to CDN77 client section 1234 passwd API password 8vL4BpXbRqgPTKA0hV36dWjMTNfIkZK8 All parameters are required. Additional notes: id of CDN resource can be found in the CDN list: API password can be found in the API section, which can be found in the client section: Limitations of prefetch API method allowed requests per second: 1 allowed requests per day: 100 Example of usage (via Linux s curl utility): Deleting CDN resource with ID 1234: curl --data "id=1234&[email protected]&passwd=your api password" It returns status : ok JSON response in success and any other response or status is failure. Example of successful delete CDN API response: {"status":"ok","description":"cdn id 1234 was deleted"}

14 2.6. Edit CDN resource Description Any CDN resource can be edited via API (via its ID). Not all settings from client section are available via API Implementation Following HTTP POST parameters is accepted on the following gateway: POST parameter name Parameter description Example of usage id login ID of CDN resource, on which the Login to CDN77 client section 1234 passwd API password 8vL4BpXbRqgPTKA0hV36dWjMTNfIkZK8 origin_url cname Origin URL from which the content will be pulled (source of files for CDN) CNAME for your CDN resource cdn.yourdomain.com cache_expiry Cache Expiry value (cache TTL) (see additional notes below this table, to see all allowed values)

15 url_signing_on Switch token authentication setting values: 1 = url signing enabled 0 = url signing disabled url_signing_key Set token authentication key (password) rkybztaapfhsv5nd (it must be 16 characters long) All parameters are optional, except for id, login and password, which are required. Additional notes: id of CDN resource can be found in the CDN list: API password can be found in the API section, which can be found in the client section: Limitations of prefetch API method allowed requests per second: 1 allowed requests per day: 1000 allowed cache_expiry values: 10, 30, 60, 240, 720, 1440, 2880, 4320, 5760, 7200, 8640, 10080, 11520, 12960, 14400, 15840, cache_expiry values are in minutes cache_expiry value can be overridden by setting custom Expires and Cache-Control headers on the origin url_signing_key must be equal 16 characters Example of usage (via Linux s curl utility): Editing CDN resource with ID 1234: curl --data "[email protected]&passwd=your api password&id=1234&origin_url= _key=abcdefghij123456"

16 It returns status : ok JSON response in success and any other response or status is failure. Example of successful edit CDN API response: {"status":"ok","description":"cdn id 1234 updated;origin_url updated to updated to cdn.yourwebsite.com;cache_expiry updated to 14400;url_signing_key updated to abcdefghij123456;url_signing_on updated to 1"} 2.7. Fetch statistics data Description purposes. Traffic statistics data can be fetched via API for any further processing or archiving Implementation Following HTTP POST parameters is accepted on the following gateway: POST parameter name Parameter description Example of usage id login ID of CDN resource, on which the Login to CDN77 client section 1234 [email protected] passwd API password 8vL4BpXbRqgPTKA0hV36dWjMTNfIkZK8-16 -

17 All parameters are required. Additional notes: id of CDN resource can be found in the CDN list: if id parameter set to all then traffic statistics for all CDN resources will be returned API password can be found in the API section, which can be found in the client section: Limitations of prefetch API method allowed requests per second: 1 allowed requests per day: 1000 Example of usage (via Linux s curl utility): Getting traffic statistics for CDN resource with ID 1234: curl --data "id=1234&[email protected]&passwd=your api password" It returns status : ok JSON response in success and any other response or status is failure. Example of successful CDN traffic statistics API response: {"24h":" MB","48h":" MB","30d":"14.67 GB","02m":"0 Bytes","01m":"35.56 GB","00m":"14.67 GB"}

18 Getting traffic statistics for all CDN resources: curl --data api password" It returns status : ok JSON response in success and any other response or status is failure. Example of successful CDN traffic statistics API response: {"24h":" MB","48h":" MB","30d":"36.61 GB","02m":" KB","01m":" GB","00m":"29.05 GB"} 2.8. Get CDN details Description Get details (of settings) of CDN resource Implementation Following HTTP POST parameters is accepted on the following gateway: POST parameter name Parameter description Example of usage id login ID of CDN resource, on which the Login to CDN77 client section 1234 [email protected] passwd API password 8vL4BpXbRqgPTKA0hV36dWjMTNfIkZK8-18 -

19 All parameters are required, except for id parameter

20 Additional notes: id of CDN resource can be found in the CDN list: if id parameter is missing, details for all CDN resources will be shown (this could take a while) API password can be found in the API section, which can be found in the client section: Limitations of prefetch API method allowed requests per second: 1 allowed requests per day: 1000 Getting details of settings for CDN resource with ID 1234: curl --data "id=1234&[email protected]&passwd=your api password" It returns status : ok JSON response in success and any other response or status is failure. Example of successful CDN traffic statistics API response: {"status":"ok","description":[{"id":1234,"origin_url":" et","cache_expiry":2880,"url_signing_on":false,"url_signing_key":""}]} Getting details of settings for all CDN resources: curl --data "[email protected]&passwd=your api password"

21 It returns status : ok JSON response in success and any other response or status is failure. Example of successful CDN traffic statistics API response: {"status":"ok","description":[{"id":4004,"origin_url":" "cdn_url":" r.cdn77.net","cache_expiry":14400,"url_signing_on":true,"url_signing_key":"abcd5mn6ipzpjmxd"}, {"id":3308,"origin_url":" "cache_expiry":2160,"url_signing_on":false,"url_signing_key":""}]}