Step by step guide
==================

API Key generation
***********************

	1. Register on the Zillin website https://zillin.io/
	2. Go to the ‘API’ tab.
	3. Add key:

	.. image:: images/generate-new-api-key.png
		:width: 800px
		:alt: alternate text
		:align: center
		
	|
	
	4. The newly generated key will be shown below.
			
	.. image:: images/get-api-key.png
		:width: 800px
		:alt: alternate text
		:align: center

Choosing API Version
********************

	To make a request to specific API version, you need to add authentication header with name 'api-version' and value of version e.g '2.0'

	If no header will be present, the request will be sent to the default version. Currently, the default version is 1.0.

	Additionally, we have added response headers 'api-supported-versions' and 'api-deprecated-versions' with information about current supported and deprecated versions.
		
First request
****************

	Descriptions of available methods can be found here: |PublicApiSwaggerUrl|

	Each request requires authorization header with API key: "Authorization: c4dc6d89c92f453d8d67e571120b3bb4"

	Requests can be made in many different ways like:

Using our site
----------------------------

	1. Go to: |PublicApiSwaggerUrl|
	2. Click the 'Authorize' button.

	.. image:: images/swagger-authorize.png
			:width: 800px
			:alt: alternate text
			:align: center
		
	|
	
	3. Paste and confirm API key.

	.. image:: images/swagger-authorize-set-api-key.png
			:width: 400px
			:alt: alternate text
			:align: center
		
	|
		
	4. Choose desired method e.g 'get datasets'

	.. image:: images/swagger-select-method.png
			:width: 800px
			:alt: alternate text
			:align: center
		
	|
				
	5. Click 'try it out' button

	.. image:: images/swagger-try-method.png
			:width: 800px
			:alt: alternate text
			:align: center
		
	|
				
	6. Set required workspaceId parameter (can be obtained by 'get workspaces' method) and optionally API version.

	.. image:: images/swagger-set-required-data.png
			:width: 800px
			:alt: alternate text
			:align: center
		
	|
	
	7. Click 'execute' button

	.. image:: images/swagger-run-method.png
			:width: 800px
			:alt: alternate text
			:align: center
		
	|
				
	8. The response body with response headers will be shown below.

	.. image:: images/swagger-response.png
			:width: 800px
			:alt: alternate text
			:align: center
	
Using Postman
-----------------------------------------

	1. Choose a method, URL and set authorization type to 'No Auth'

	.. image:: images/postman-set-method.png
			:width: 800px
			:alt: alternate text
			:align: center
		
	|
			
	2. Move to the headers tab, add required headers:

	.. image:: images/postman-set-headers.png
			:width: 800px
			:alt: alternate text
			:align: center
		
	|
	
	3. Move to the params tab, add required paramater and send request:

	.. image:: images/postman-set-params.png
			:width: 800px
			:alt: alternate text
			:align: center
		
	|
				
	4. Response body and headers will be shown below

	.. image:: images/postman-response.png
			:width: 800px
			:alt: alternate text
			:align: center
		
Using command line with curl
-----------------------------------------

	Authorization header: 		"Authorization: c4dc6d89c92f453d8d67e571120b3bb4"

	API version header: 		"api-version: 1"

	Response type header: 		"accept: text/plain"

	Choosen method: 			GET "|ExampleApiEndpoint|"

	1. Run the whole command:

	curl -X GET "|ExampleApiEndpoint|" -H "Authorization: c4dc6d89c92f453d8d67e571120b3bb4" -H "api-version: 1" -H "accept: text/plain"

	.. image:: images/curl-run-command.png
			:width: 800px
			:alt: alternate text
			:align: center
		
	|
				
	2. The response will be shown below:
			
	.. image:: images/curl-response.png
			:width: 800px
			:alt: alternate text
			:align: center		

Using API in your own application
**************************************

To use API in your application you need to generate a client.

Many developers still hardcode their clients.
It might not be a good solution, because it increases the possibilities of bugs in the specification.
It is inefficient as well. The better way to generate your clients is to use a swagger editor.

Generating client with the online swagger editor
------------------------------------------------

	1. Go to page https://editor.swagger.io/

	2. Select 'file' and 'import URL'

	.. image:: images/generate-client-select-url.png
			:width: 800px
			:alt: alternate text
			:align: center	
		
	|
					
	3. Find the desired URL on our website |PublicApiSwaggerUrl|
	
	4. Choose the version and click the link from the left:
	
	.. image:: images/select-our-api-version-and-json-url.png
		:width: 800px
		:alt: alternate text
		:align: center
			
	|
	
	5. Paste URL into the box and click the 'ok' button.
	
	.. image:: images/paste-swagger-api-json-to-online-editor.png
		:width: 400px
		:alt: alternate text
		:align: center
			
	|
	
	6. Choose the desired language e.g python
	
	.. image:: images/choose-language-to-generate-client.png
		:width: 800px
		:alt: alternate text
		:align: center
				
	|
	
	7. Save the zip file. The 'swagger_client' folder will display models and APIs:
	
	.. image:: images/python-client-models-and-api.png
		:width: 400px
		:alt: alternate text
		:align: center