Before you start building your own requests, you need a tool to send them with. In this installment, we'll show you the Postman application, which we use for all testing on Flexi support, and walk through user login.
What to use to call the REST API
For getting familiar with the API and for testing, we recommend Postman. It offers a clear graphical interface where you can easily build even more complex requests and immediately see the server's response. It's freely available for download on the manufacturer's website; we recommend the desktop application.
However, Postman isn't the only option. Data can also be read directly in a browser, requests can be sent from the command line using the cURL tool, or you can write your own script. A production integration of Flexi with another system will ultimately always rely on custom code, but for getting to know the interface and for debugging, Postman is the fastest option.
💡 You can try out the individual tools hands-on in the API Ninja series, which has its own test environment prepared for this purpose.
User login
Before any operation, you first need to log in. In Postman, this is handled by the Authorization tab (called Auth in older versions), where you enter your login credentials. For testing purposes, Basic Auth is sufficient.
If you want to use a particular user exclusively for REST API access, set up an API user. API access is purchased separately and costs the same as one standard access for the given license tier; there is no limit on the number of API users. Details are described in the article on licensing API access, and you can find pricing in the price list.
⚠️ Always send login credentials over HTTPS, and never include them directly in the URL. Credentials in a URL get stored in server logs and browser history. Also, make sure the API user is granted only the permissions that the integration actually needs.
Basic Auth is the simplest login method and is sufficient for getting familiar with the API. For long-running integrations, JSON authentication is more suitable, where you request an authentication token once and then send it along with subsequent requests. Both methods, including login via SAMLv2 and OpenID, are described in the article on authentication.
The Postman interface step by step
You'll need the following areas of the interface for every request.
1. Selecting the HTTP operation
Postman offers a wide range of operations; for working with Flexi, three are enough: GET, POST, and PUT. We'll explain their meaning in the installment on reading, writing, and deleting records.
2. The URL field
This is where you enter the address that Postman will work with. The way to construct it is described in the installment on building the URL address.
3. The format of the data being sent
This area only matters when you're writing data to Flexi.
⚠️ Make sure the URL extension matches the format of the data you're sending. If you send XML to an address ending in .json, the request will fail with an error.
4. The form of the created request
This relates to the previous point and again only applies to sending data. By default, select raw.
5. Server response
This is where the response from Flexi is displayed after sending the request:
for the
GEToperation, it's the requested data in the selected format, typically XML or JSONfor the
POSTandPUToperations, it's the result of the operation, i.e., whether it completed successfully, and the identifier of the affected record
6. Request body
This area is where you enter the content of the request in XML or JSON format, i.e., the data you want to save to Flexi.
The example shown creates an issued invoice with the code TESTFAKTURA, document type FAKTURA (standard invoice), issued on 1/1/2018, with variable symbol 20180101. You'll find more examples in the final installment of the series.
Other installments in the series
Postman and user login (this article)