When learning how to interface with a new REST API, it’s always helpful to verify your connections and queries in a standalone client before moving the new integration to code. My preferred program is the Advanced REST Client, but there are plenty of other popular options such as Postman or SoapUI. If you want, you can even do all your testing purely in the command line by creating and executing curl commands. All the options will produce the same requests out to the REST service that you’re targeting, so it comes down to personal preference.

Once you have your client set up, the next step is to find the service’s API documentation. These are usually publicly accessible and should list everything that you need to know about what the REST service expects from requests as well as exactly what it returns. We’ll be looking at M-Files’ REST API, whose documentation is here.

Most APIs use a special authentication token that is generated at the start of the process and is used in all subsequent calls so that we aren’t passing our user credentials on every call. For the M-Files API, this is the Authentication Tokens call. The Input section on that page is a link to the object that it expects when reading in the POST body of a request, though not all the fields listed on the page are required. From the getting started page, we can see that the required fields are Username, Password, and VaultGuid.

Putting this together into ARC, we’re going to be making POST to /REST/server/authenticationtokens. Since we’re doing a POST, we’ll be putting the parameters that the service uses into the body.

While most APIs will return an error if there’s an issue with the initial authentication, the M-Files API will return a 200 response no matter what is entered. In order the validate that response, we’re going to make a follow-up call to /REST/session. This service returns information about the currently logged-in user so it’s useful to make sure that everything has been set up correctly.

Since we’ve already sent in the authentication information, we can use the response from the /authenticationtokens call in our subsequent calls. Different APIs will have you send authentication tokens in different ways, and in M-Files case, we’ll be sending in the token in the X-Authentication header (which is documented on the getting started page). That means that the /session call looks like this.

If you get a 403 response from the /session call, that means that there’s a problem with your authentication token. The best way to verify your credentials is to take the base URL of your M-Files instance and paste it into your browser. That will bring you to the M-Files web login page where you can enter your credentials and easily verify that you’re correct.

Once /session comes back with a 200 response, you know that you’re fully authenticated and are ready to make other calls to get back information about the vault. That can include browsing the vault's views, getting the full list of properties on the vault, or finding the information about a specific object.

About TEAM IM

TEAM IM is an experienced solution company that advises, develops, implements, supports, and manages enterprise grade process, information and content management systems. For more than twenty years, TEAM IM has acted as a trusted advisor to our clients through our offices in Australia, New Zealand, Europe and the United States. Our mission is to assist our client to get the most out of their investments in technology. Whether our clients are large government agencies or corporations, construction firms, accounting firms, heavy industry, or smaller organizations, we strive to deliver demonstrable business benefits and generate real return on investment for our clients.

Our products and services offer solutions to transform your business by automating and modernizing your operations. We work hand-in-hand with our clients to understand their goals and create and execute multi-year, continuous improvement plans. Our mission is to support and manage every solution we deliver, so we take care to design long term, future proof, maintainable solutions. We work with best-in-class technology partners that we have carefully selected to ensure we can execute our plan and achieve our clients continuous improvement goals.

Our products and solutions encompass Advisory Services, Implementation Services and Managed Support Services. We specialize in Business Process Automation and Optimization, Content Platforms and Content Services and we are also a leader in Mobile App/Field Services software development and Digital Workplaces. We have industry-specific solutions for the Construction and Accounting Services sectors, and cross-industry solutions for Accounts Payable, Contract Management, App Modernization, Field Services and File Sharing.

At TEAM IM we are passionate about delivering outstanding outcomes for you, our clients.