HTTP for Integrators
When building an API for the first time, you’ll notice there are a number of different HTTP methods you can use. Though most examples online seem to only use two: GET and POST. While these two get the job done, they aren’t the only methods you will always want to use.
In this post we’ll examine the six methods you will likely find in the wild. If you’ve researched HTTP methods, you may notice that we have omitted OPTIONS and TRACE. This is because they are rarely implemented in the types of systems used in manufacturing. And since most APIs are clearly documented, you don’t need to worry about the OPTIONS method for retrieving information on the server. TRACE is generally used for testing and as a rule is turned off on most production systems.
CRUD
Most manufacturing systems will use the concept of Create, Read, Update, Delete (CRUD) endpoints for any API/server based architectures.
This means the server will have endpoints (or URLs) you can call to:
Create records
Read methods to retrieve records and return details about them
Update methods to modify records
Delete methods to delete records.
Note that the endpoints you can call will reference a particular HTTP method which limits what you can do with each endpoint. This has a bit of built in error handling to prevent updating records with a Read call for example.
GET
The first method anyone interacting with HTTP will use is GET. If you go to a web site in a browser this is what your browser uses to pull in all of the information from the internet and load a web page. This simply “gets” data from the underlying source and returns it to the calling system. The data can take many forms: HTML, JSON, or raw text to name a few. In the CRUD world, this is mainly used for the “Read” endpoints to retrieve records.
GET methods can be cached, meaning you can request data once and—based on various configuration settings—that data will be cached for a period of time. If you request the same data again while the cache is still valid, it will return the cached version, speeding up the overall request and reducing overall network bandwidth usage.
The limitation with GET requests is they should only be used to retrieve data and not to send data. An exception is using query parameters in URLs to include data for the responding system to use as inputs when generating data. An example is if you look at the current url in your browser on this page and see the /HTTP-for-integrators at the end, or if you ever see something like ?param=ABC¶m2=123 in a URL. These are parameters that the receiving system can use to refine the data it will return.
Important Notes on GET Requests:
GET requests can be cached
GET requests remain in the browser history (you can use the back button)
GET requests can be bookmarked
GET requests should never be used when dealing with sensitive data
GET requests have length restrictions (URLs can be a maximum of 2048 characters, returned data can vary by browser/system)
GET requests are only used to request data (not modify data)
POST
NOTE: POST methods won’t work if you simply go to the URL in a browser. You either need to explicitly call a POST from your program, or you need to use something like Postman to call the endpoints using a POST method. Some browsers will have extensions you can install for this purpose, but you will need to use a tool to call a POST method besides a browser.
The opposite side of the “first HTTP methods coin” is the POST method. Based on the HTTP specification and in general usage, a POST method should be used to create data on the receiving system. You can get into a semantics argument about using a POST method to update records or a PUT method instead (which we will describe next), however the correct method will be determined by the system you are interfacing with—unless you are building that too. In most CRUD systems this method is used on the “Create”, “Update”, and “Delete” endpoints, although one could argue it should only be used on “Create”.
In a “proper” implementation you could call a POST request with the same data—to create a user in a system for example—and you would end up with two users with identical information (but different ID values) in the database.
In most manufacturing implementations, a POST request is used to create or update information—depending on if the record exists or not. The record status is determined by passing in an identifying value like an ID when making the call, or calling a “Create” method for adding a user, and an “Edit” method when updating a user.
Important Notes on POST Requests:
POST requests are never cached
POST requests do not remain in the browser history (back button won’t work)
POST requests cannot be bookmarked
POST requests have no restrictions on data length
PUT
The PUT method basically follows the same concept as a POST method from the system calling it, sending data to the end point, and expecting something to get modified. The difference between the two depends on the specific implementation you are working with. In the CRUD architecture, PUT could be used for “Create”, “Update”, and “Delete” although a valid argument could be made that it should only be used for “Update.”
In an ideal world, you would use a PUT method to update something and if you called the method with the same data multiple times you would receive the same result. You could theoretically use PUT methods instead of POST methods if your endpoint uses the concept of “upserts” or “if this record exists update it, otherwise insert it into the database.” In most cases this is how POST operations will function unless the server has clearly defined and separated function calls.
DELETE
Following along the same path for modifying data in the underlying system with POST and PUT, another method that inspires plenty of discussion is the DELETE method. Use this method to delete a record from the underlying system. Based on the implementation of the system you are interacting with, you could also do this using a POST method (or even a PUT method) although if you use a PUT, not also using DELETE would be madness!
Functionally, the DELETE method is the same as a PUT and POST from the calling system’s perspective. The difference in execution happens on the server side to delete a record.
PATCH
A less common HTTP method for updating data is a PATCH call. PATCH is typically used to perform a non-comprehensive update to a record. This could be modifying a user’s address and sending over only the address fields that need to change (while omitting the username, phone number, email address, etc.) Using the PATCH method is very similar to POST/PUT but uses a smaller overall bandwidth footprint. Depending on the implementation, using PATCH can lead to a more secure system by not allowing inadvertent updates to the entirety of a record.
HEAD
A HEAD method call is essentially identical to a GET call minus the response body that’s returned. This is useful for validating an HTTP server’s connectivity if a particular endpoint exists without having to retrieve records from the system. If the method exists and is called with a HEAD call, it will return a result without the response body that would be returned using a GET call. HEAD calls are relatively uncommon in most custom API implementations as in most cases you would simply use a GET call because you would want to access data, and you would receive an error if the endpoint didn’t exist.
Wrapping Up HTTP for Integrators
Now that you have learned about the available HTTP methods, review our post on Using Ignition as an API Backend to learn the various options for building a robust API in Ignition. If you have API documentation for a system you are trying to integrate with, you will now be able to see how the various HTTP methods have been implemented—and if they have been used correctly!
As with any technology, there are always exceptions to the rule. If you are building an API and need to support an older version of Internet Explorer for example, you might need to use a POST method for some calls to work properly when other browsers could use a GET without issue. If you run into cases like that, please let us know and we can share some of our experiences to help you out.
