1. Apply for an API key
The first thing you need to do is obtain an API key. The API keys are available only for users with active Team or Elite accounts. Please note that the API key is secret and you should not disclose or share it with anyone else.
2. Choose an API method
Flipsnack API has two endpoints which receive API calls:
- http://upload.flipsnack.com/v1 - for upload requests
- http://api.flipsnack.com/v1 - for the all other requests
Once you identify the correct endpoint, you must select one of the API methods, depending on what action you wish to perform. You can select the action from the API methods listed in the API Reference.
Each method must receive a set of parameters. You must send these parameters as part of the URL when using HTTP GET requests or inside the HTTP body for HTTP POST requests. When uploading files you must use HTTP POST with encoding multipart/form-data. All other requests must be made using HTTP GET.
3. Make a request
The request (either through POST or GET) must contain at least 3 parameters. The mandatory parameters are:
- apiKey - required for authentication. We associate the user to the API key provided
- signature - required for authentication. Please read How to sign requests to see how to calculate the parameter
- action - specifies which method should be executed
You can also specify the format of the response (either JSON or XML) using the format parameter.
4. Parse the response
By default, the response from the API will be in JSON format. But you can also request a XML formatted response using the format parameter.
The response body will contain 3 parameters:
- code - the status code of the response (20 for 'OK'). See other status codes returned by the API
- status - the status message corresponding to the status code
- data - the actual data sent from the API server
If the request does not need data returned from the server (e.g. delete operations) or if the response is an error, the data parameter will be missing.
5. Handle errors
In case of errors, the response will contain the error code (the code parameter) along with the error message associated (the status parameter). Error messages have a code value higher than 20. Please see the list of status codes for more details.
Note: Status messages are only descriptive. We recommend you to use the status code when checking API responses. You can find the explanation for each status code in the status codes list.