Authorization Basic (Basic Auth)

The API authenticates every request via the HTTP 1.1 Authorization Basic header. The header takes the following format, where [username] is the API key provided to you by TFM, and [password] is always left blank. The [username]:[password] combination should be base 64 encoded before being placed in the header.

Authorization: Basic [username]:[password]\r\n

Anatomy of a Request

Making a request is fairly simple, and done via POST or GET. You can specify the type of return you want:

• Text (a recursively printed representation of an associative array)
• JSON
• or XML

Both POST and GET requests can return a response containing any data requested (or generated as a result of the request) and a message stack (when available). If you’re unfamiliar with POST and GET over HTTP, they can be thought of as programmatically submitting a form to a URL and specifying the POST or GET type for the METHOD attribute of the <FORM> tag.

<form method="POST" action="...">
</form>
<form method="GET" action="...">
</form>

Request URI

The request URI takes the following format

https://tms.targetfmi.com/index.php?p=api&r=text&c={category}&m={module}[&d=data1[/dat2[/...]]]

POST

POST requests are formed (in the most basic manner) by passing the request array() or stdClass() to http_build_query() and using the result in the content index of the options associative array passed to stream_context_create(). Both methods ( array() and stdClass()) will be demonstrated for the various POST endpoints in the API.

GET

GET requests are formed by passing the data represented in the request in the d portion of the request URI. Each piece of data is separated by a /, the order in which parameters are passed will be specified, and should be followed.

Authentication in Postman

In the Authorization tab of a request, select Basic Auth and provide your API key as the username, leaving password blank.

VB.Net Developers

If you're integrating with VB.Net, or another .NET variant (like C# or ASP) you may find the example project included here useful. If you've never worked with .NET and RESTful APIs before, the easiest way to understand the request is to think of it as a Web form and how you would handle submitting data programmatically to simulate a form Submission. We've created a sample project you can use as a starting point. Please note that there are several ways to communicate with an RESTful API in .NET and each have their pros and cons and we've chosen to use the System.Net.WebClient in our example. We chose WebClient because it illustrates really well the driving principles of REST: stateless transactions based on the HTTP standard. The example code is just that, an example and should not be used for production applications. The provided code should be able run as-is and was tested with Visual Studio 2012 Express Edition.

Anatomy of a Response

The response will always include 2 parts, the Body and the Message stack.

Array
(
	[body] => Array
	(
	)
	[message] => Array
	(
		[0] => Array
		(
			[type] => [success|info|warning|error]
			[message] => A message.
			[stacktrace] => Array
			(
				[0] => Container
				[1] => Module
				[2] => x.n
			)
		)
	)
)

Body

This is where any data that is returned as a result of your POST or GET request is stored. The format will vary depending on what is being returned.

Message

Any messages returned by the server are stored here. The message stack takes the format of an array of message arrays. The following table describes each node and what it can contain.

Error Codes

The API (in almost all cases) returns a 2-part error code. The first part is an HTTP 1.1 status code (defined by RFC 2616). The second part, following the decimal point (dot) is a breakpoint code. When reporting errors that occur beyond your control you should include the entire, unadulterated message stack in your report of the problem. If there is no decimal point, then the code is exclusively a breakpoint code.