Common Terminology

REST API

A REST API provides a way for different software applications to talk to each other over the Internet. It provides a set of rules and conventions that make it easier to send and receive information between applications. A common way of thinking about APIs and Web Servers is to think about it like a restaurant. When you come to the Authenticx API restaurant your menu is a list of all the possible routes you can make a request to. You can then make an HTTP request to one of those routes, similar to a server taking your order, and then whatever you ordered will be served to you.

Resource

A resource refers to a specific entity or object that is made available through the API. It represents a piece of data or information that can be accessed, manipulated, or acted upon by clients through HTTP requests.

Route

A route is a path to a specific resource, that includes any patterns such as route or query parameters. A route tells the server what resource you want to access and parameters help you to navigate and narrow down what specific resources you want.

• Route Parameters

  A route parameter is a special kind of information that you include in the route itself. It acts as a placeholder for a specific value that you want to retrieve and will always be surrounded by { }. In the Authenticx API you will often see route parameters used when you wish to request a specific resource by its id. An example of a route parameter in our API is seen below.

/Agent/{AgentId}

// Lets look at this route one step at a time. First we have /Agent, this indicates that
// we are targeting the Agent resource. Next we have /{AgentId} which means we want an agent
// with a specific id. Remember, {AgentId} just acts as a placeholder for a value, when you
// construct the concrete route, you should replace it with the id of the agent you wish to get.
// For example: /Agent/e846a04f-3f77-40c7-aa25-352514665336

• Query Parameters

  A query parameter is an additional piece of information that you can add to your API request. It helps you refine your request and ask for specific data by using a key-value pair. The first query parameter in a route always starts with ? and any subsequent query parameters will start with &. Below is an example using query parameters.

/Evaluations/?StartDate=2022-07-07&EndDate=2022-07-20&Status=Completed

// Again lets look at this route one step at a time. First we have /Evaluations, this indicates
// that we are targeting the Evaluations resource. Next we have 3 query parameters, StartDate,
// EndDate, and Status. Each parameter should be a key value pair as seen above. Also, notice 
// that we have supplied concrete values, unlike the place holders seen with route parameters.
// This mainly comes down to the fact the query parameters are not required so we have no way
// of knowing beforehand which are supplied.

(HTTP) Method

HTTP methods are different actions you can take when talking to an API. They tell the API what you want to do with the data. The main ones are GET, POST, PUT, and DELETE. However, our API only provides routes with GET, POST, and PUT methods.

• GET

  GET is an HTTP method that you use when you want to retrieve information from an API. When making a GET request you will never supply a request body. This is because you only wish to retrieve information, the request body is often reserved for new or updated information and is used with POST and PUT requests.

• POST

  POST is an HTTP method that you use when you want to send new information to the API. POST is often used for the creation of a new resource and most likely corresponds to a record being added to a database table.

• PUT

  PUT is an HTTP method that you use when you want to update or replace existing information in the API.