This guide describes how to use the Swagger UI Tool to test API Calls before implementing them.
Note - this guide is currently under construction and uses the TESTNET API URL for all examples, once V2 is fully released, this will be updated.
Swagger is a web-based UI that allows you to test all available API Method Calls. All of the code is pre constructed, allowing you to 'drop in' your specific parameters and check the results are as you expect, before you take the time to implement it yourself.
You can also use Swagger to better understand any errors you may be encountering and we would encourage reviewing this before contacting our support teams.
You can access Swagger through the following links:
Note - using the Production Swagger will make actual production API calls. So it is advised to use the testnet. The only noticeable difference between the two will be the URL which will contain 'testnet'.
As the page loads you will be greeted with a list of available methods, to use any of these, you will need to first create an API Key on your NMKR Studio Testnet account.
A snippet of some of the available methods
You will also see that each method can be expanded to reveal various useful options and information:
These are the inputs required for this specific method call
These are all of the possible, pre defined HTTP response codes + data that the API will respond with, based on the result of your attempted method call
Run the test method call
The Specific HTTP Response to this specific attempted method call
There are many HTTP Responses, so we are going to cover those that are most relevant to the NMKR Studio API.
HTTP response Codes are made up of 3 digits:
First Digit is the category
Second and Third Digits define the subcategory
Codes beginning with 2 mean that you submitted a valid API method call, that executed correctly. At a high level, you will be looking to see the '200' response, which is literally translated to mean 'OK' this is good and means that the method executed correctly.
Codes beginning with 4 mean that you submitted an invalid API method call, the NMKR Studio Servers handled this and returned information about what was wrong. You can then compare this with the Swagger Documentation to fix the error. Common responses will be '401' where there is an issue with your API Key and '404' where the UID of the project/NFT was not found.
Codes beginning with 5 mean that there has been an issue on the server side. These will be rarer that 2's or 4's and may not be related to the way you have constructed your method call. The '503' error for example will appear in the unlikely event that our API service is unavailable.
You will see that every method has a predefined set of likely responses, with the additional information of what the response payload will return with.
Fixing Specific Errors
Note - look carefully at this, as we have added information as to how the HTTP codes correspond with the NMKR Studio API Method Calls within the Swagger UI Documentation.
For example, in the method 'MintAndSendRandom' if you receive a '406' error this generically means that 'it doesn't match criteria'. A quick look in the details will show that this actually means that the receiver address you have specified, is not a valid Cardano Address.
The 406 Error on MintAndSendRandom
Note - this is where Swagger can really help with troubleshooting.
Mozilla have a really good guide on general HTTP Error codes but you will need to use Swagger to see how EXACTLY they relate to the NMKR Studio API.
Try It Out!
Global Page Authentication
The first action before you can try it out, is to add your API key in the global page authorisation panel. If you do not do this, you will ALWAYS receive a 401 Error when using Swagger UI.
To do this, navigate to the top right of the page and select the 'Authorize' Button. You will then be greeted by a pop up, where you should copy and paste your API Key mentioned previously.
Example Method - GetCounts
You can then navigate to a method of your choosing (in this case we are showing the GetCounts method) and expand the row.
The GetCounts Method
You will notice the 'Try It Out' Button, press this to unlock the editable input parameters.
The 'Try It Out' Button
In this case, it asked for our API Key (this needs to match what you put in the global auth) and the project UID for the project we want to see the count of NFT status' for.
Example with obfuscated parameters
Project UID = aaaaaaa-bbbb-cccc-dddd-eeeeeeeeee
API Key = xxxxxxxxxxxxxxxxxxxxxxx
You will then be able to execute the test, if everything is working correctly, you will see the classic sign of good news 'HTTP 200', plus the payload of information you were looking for!
HTTP 200 OK Response
The HTTP 401 Error
This is probably due to having not (or incorrectly configured) your global page authentication. Please see this section to check this is correct. If this is correct, then you may have added a miss-matched or incorrect API Key into the Authorisation Parameter in that specific method.
Other errors will very likely be in the same format, but will be specific to the method call. For this reason, the best course of action is to review this section and make sure to study the responses for the specific method you are working with.