API help
CWG API can be used to access CWG Collection from third party applications. This API is not full feature yet. For methods that are not supported here, you can use legacy API which you will find here.
Accessing the API
This API is located at https://cwg.gcm.cz/api/v1/.
All communication with the API must be in UTF-8 encoding.
You can access the API using many different protocols. Supported protocols are:
Plain requests
Call API methods like this:
https://cwg.gcm.cz/api/v1/system/methodHelp?methodName=system.listMethods
You can pass parameters using GET or POST, this method however does not support passing structs as parameters.
By using Accept
HTTP header, you can specify how you want to encode the output. Default is JSON, but you can
specify Accept: text/xml
to receive XML output similar to XML-RPC format.
For example:
GET /api/v1/system/methodHelp?methodName=system.listMethods HTTP/1.0 Host: cwg.gcm.cz
You will receive following response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Content-Length: 124 "List registered RPC methods.\n...."
(output is shortened, some headers skipped)
Plain JSON requests
If you want to use this simple API and pass more complex structures as parameters, you can use JSON instead of standard application/x-www-form-urlencoded.
For example:
POST /api/v1/system/methodHelp HTTP/1.0 Host: cwg.gcm.czContent-Type: text/json Accept: text/json {"methodName": "system.listMethods", "params": []}
You will receive following response:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Content-Length: 124 "List registered RPC methods.\n...."
(output is shortened, some headers skipped)
JSON-RPC
You can use standard JSON-RPC protocol by calling https://cwg.gcm.cz/api/v1/RPC2
and passing JSON-RPC request
using plain POST method.
For example:
POST /api/v1/RPC2 HTTP/1.0 Host: cwg.gcm.czContent-Type: application/json Content-Length: 129 {"method": "system.methodHelp", "params": ["system.listMethods"], "jsonrpc": "2.0", "id": "4881ecd9-5a1e-4f36-ba8f-58cccf52b569"}
You will receive following response:
HTTP/1.1 200 OK Content-Type: application/json-rpc; charset=utf-8 Content-Length: 192 {"result":"List registered RPC methods.\n...","error":null,"id":"4881ecd9-5a1e-4f36-ba8f-58cccf52b569"}
(output is shortened, some headers skipped)
You can find JSON-RPC documentation here: http://www.jsonrpc.org/specification
XML-RPC
You can also call the API using XML-RPC protocol. The XML-RPC endpoint is also located at https://cwg.gcm.cz/api/v1/RPC2
.
For example:
POST /api/v1/RPC2 HTTP/1.0 Host: cwg.gcm.czContent-Type: text/xml Accept: text/xml Content-Length: 179 <?xml version="1.0"?> <methodCall> <methodName>system.methodHelp</methodName> <params> <param> <value><string>system.listMethods</string></value> </param> </params> </methodCall>
You will receive following response:
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 257 <?xml version="1.0" encoding="utf-8"?> <methodResponse> <params> <param> <value> <string>List registered RPC methods....</string> </value> </param> </params> </methodResponse>
You can find XML-RPC documentation here: http://xmlrpc.scripting.com/spec.html
Authentication
Most of API methods requires you to authenticate yourself and use access token to be able to call the method. You can obtain the token by using OAuth2 authorization mechanism.
Most simple example of the authorization using OAuth2 is defined in following diagram:
- Register your application in the Applications manager.
- Redirect your user to OAuth2 authorization page:
https://cwg.gcm.cz/oauth2/authorize/?client_id=your-application-id&redirect_uri=your-application-redirect-uri&response_type=code
- Wait for user to log in and confirm the authorization.
- You will receive authorization code on
your-application-redirect-uri?code=access-code
. - Request access token by calling
https://cwg.gcm.cz/oauth2/token/?client_id=your-application-id&client_secret=your-application-secret&code=authorization-code-from-previous-step
Few notes regarding the OAuth2 authentication:
- Authorization code is valid for 30 minutes.
- Access token is valid one year.
- You are responsible for keeping application secret secure.
- Access to the API by your application can be revoked in case of excessive usage of API that causes service disturption.