Tue, Dec
5 New Articles

REST: A Primer for Building Web and Mobile Apps

Development Tools / Utilities
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

REST: REpresentational State Transfer. That's what it means and where it comes from, but what is it and why should we care? Hopefully, this article will take care of that part.


You hear a lot about REST today. Of course, that does depend on where you're standing, who you're talking with, and whether you're paying attention. But if you're standing in the right spot, talking to web-oriented developers, and actually listening to what they're saying, you'll hear a lot about REST. And that's good because REST is becoming the default architecture to use for web apps today, particularly mobile. But what is REST, and how can you use it?

Let's start by saying that when you create a web app, you're going to use web services to interact with the web resources that are being held on the server. How you build those web services will be very important in how the app works, and REST is one way in which you can build web services.

Maybe the best way to describe REST is as an "architecture style" (courtesy of Dr. M. Elkstein). It's not an architecture per se, but a way or "style" of building your web services. It's not standardized as SOAP is. There's no W3C document describing what you need to do for a service to be "RESTful," but there are tons of articles and books devoted to it. REST is most often compared to SOAP, which was originally developed for Microsoft and is another way to consume or support web services.

Technically, there are three main architecture styles that you can use to support your need for web information: RPC, SOA or SOAP, and REST.

  • Of these, Remote Procedure Call (RPC) is the oldest and approaches the task in terms of operations or activities.
  • Service-Oriented Architecture (SOA) and SOAP (which describes the communications portion of SOA) are sometimes seen as interchangeable, and many articles will reference one or the other. We're going to refer to this implementation as SOAP. It was actually a refinement (standardization) of RPC, and it looks at things from a message or data point of view.
  • REST is a relative newcomer to the arena, not in terms of actual age but in terms of people paying attention to it and the focus on resources (a web page or table element, for example).

REST was originally described in the doctorial dissertation of Dr. Roy Fielding, who was one of the developers of HTTP. In that paper, Fielding laid out very clearly what he saw as the foundational aspects of REST.

Foundational Aspects of REST

REST rests on four basic principles, and any web service that meets these criteria can be considered RESTful. Sounds very peaceful and nice, doesn't it?

First, "Representational" means that, when we access something using a RESTful web service, what we get back is just the representation of the resource we're accessing, not the actual resource. In other words, if we use a RESTful web service to access a data base, what's returned to us is an XML or JSON data stream that represents that actual database, not the database itself. I know that sounds like splitting hairs, but it's an important distinction and it allows you to specify (XML or JSON) exactly how you would like to receive the data you're accessing.

Second, "State" means that all RESTful web services will be stateless from a server point of view. Remember, there are two sides to any web service request: the client side that's making the request (that is, you) and the server side that's fulfilling the request (that is, the place where the resource you're going after resides on the web). REST requires that you not keep any information about the state of a request on the server where state information is that keeps track of what the status of the request is. In other words, every request for resources must stand alone and carry the data required to define this request. The server is not allowed to store any information that would help in this process or that could be used later. All state information is kept solely on the client side.

Third, "Transfer" refers to how the data is shared between the server and the client sides. REST is generally associated with using HTTP as the transfer method or protocol, but that's not required. You can use whatever protocol you would like, but as I said, the general method used with REST is HTTP due to its simplicity and flexibility.

OK, let's stop for a minute and look back over that because that's a mouthful and more. If there's a heart and soul to REST, it's in the facts that you get to choose both your data transfer mechanism (XML or JSON, for example) and the protocol that's used, that you're passing only a representation of the data (not the actual data itself), and that you don't keep data on the server that defines the general conversation (each REST request stands on its own without saving any information from a previous request). In the end, it provides a simple (relatively speaking) and flexible way to access resources.

Characteristics of REST

Above, we looked at the basic assumptions REST is based on, but here are some specific characteristics it has.

Everything Is a URI

Everything in a RESTful request is defined as a separate Uniform Resource Identifier (URI). Since this is the way the web is actually structured, it makes perfect, simple sense.

It also has the added benefit of not describing in the request itself, what data you're going after. For example, if you look at many sites, the URI that shows up when you make a request is the actual SQL inquiry that's used to get this information, thus providing hackers with important information on the structure of your site.

Hyperlinks Are Key

The web itself is organized and connected by means of hyperlinks. And that's the way control is handled in REST. By limiting the movement of control to actions within the resources themselves (for example, a hyperlink on a page), REST provides a simple and yet intuitive way to move from one spot to another.

Statelessness Simplifies

The fact that the server never has to keep information about a request after it is completed and then match it up with the next request that comes in from that same thread greatly simplifies the programming required on the server side and removes overhead. All of the state information resides on the client side, which has a vested interest in remembering where a given request is in the total app.

The Transport Mechanism Allows Flexibility

Because REST doesn't dictate what protocol you use, you're free to use whatever seems best to you. Granted, almost always we see HTTP being used with REST, but the reasons for that are twofold. First, REST lets you make the decision about what you will use. Second, HTTP is a very powerful yet simple protocol, utilizing four basic operations (GET, POST, PUT, and DELETE) to do all transfers, making it a natural choice if you have the option to choose.

Some Thoughts on REST Applications

REST is simple, but you need to think about a couple of things as you get ready to build a REST app.

State or Stateless

I don't want to beat this into the ground, but you have to decide which side you're onthat is, what type your app on the server is. Do you need for it to keep track of where it is, or is each request to it independent?


This is something you get to decide. Some people like XML because it's the default standard for data transfer. I like JSON because it's not as tedious as XML.

Building Your URIs

Most important of all is how you build your URIsthat is, what structure they have. Since REST uses hyperlinks to these URIs to transfer control, how they're structured is very important. Here are a few tips.

  • Keep them simple; keep them short.
  • Be consistent. The URI should show a path, not be a random name. And by being consistent, it should be predictable—e.g., trees/deciduous/maple/sugar-maple
  • Do not use embedded spaces or underscores. Dashes are better for Search Engine Optimization (SEO). Avoid mixed case since that's a good way to introduce errors. Do not include extensions.
  • Do not use embedded queries, those things that start with a question mark (?).

The URI should show the structure, and even by removing the last element, you should always be able to get to a resource.

Some people feel the URI should point to a lower-level resource. That is, not a web page or a database but something more specific. I think it all depends on what level in the hierarchy you're at.

REST or SOAP? The Tale of the Tape

So, if there are three possible ways to "style" your web services, what's the best way to go? Which of the three is the best option? And that really is the best way to put this"the best option"because the truth is both REST and SOAP (RPC is really a precursor to SOAP, so we'll combine those two, even though RPC is simpler than SOAP) are well-built, mature approaches, and either one can be used. But there are differences, and the better choice depends on you and your situation.


The first difference we'll look at is the form the data can be transferred in.

SOAP is committed to XML, and you must use it to transfer the data. REST can use either XML or JSON.

XML, of course, is known for its size, as in large, and many people prefer the shorter and more efficient JSON. On the other hand, XML can transfer any type of data, whereas JSON has some restrictions. Depending on the type of data you want to transfer, and whether or not you have any bandwidth limitations (although no one ever wants to waste bandwidth), you may decide that you can't afford XML's wastefulness and therefore have to go JSON and therefore REST.


REST is simple. In short, it consists of building a URI and then using a standard protocol (generally, but not necessarily, HTTPS) to transfer the data in either XML (bloated) or JSON (not so bloated) format.

SOAP is more complex, having a formal structure associated with it and consisting of four basic parts.

  • First, the envelope, which defines the message as a SOAP message and is required
  • Second, the header, which is optional and obviously carries the header information
  • Third, and also required, the body, meaning the details of what this request is asking for
  • Fourth, and optional, the fault, where information about errors and problems is stored 

Obviously, there's a lot more structure and overhead associated with SOAP than with REST and you can look at this in two different ways. You can say that SOAP is more standardized (and that is true) while REST is more freeform. Or you can say that SOAP is more burdened with structures that don't really add anything to the user experience and REST is clean and clear in it's presentation. Up to you.


One of the key questions to ask yourself is what role the state plays in this process. That is, does the server need to know the state of the transaction so that it can return to it at a particular point, or is each request a standalone message?

If you need to keep track at the server (ASYNC processing might be one example of this) of where you are in an application, then you need SOAP. If it doesn't matter, then you can go REST.


Everyone is concerned about security these days and it rears its ugly head here as well.

In terms of transport, it's a draw because both SOAP and REST can use HTTPS and its associated encryption. Beyond that, however, there's something else to consider, something that is somewhat controversial. SOAP supporters say that sending things in an envelope over HTTP or HTTPS is all the security you need. REST advocates counter by pointing out that with a RESTful request, the administrator (the firewall) is able to look at the request without breaking into an envelope and determine based on the HTTP command that's being issued (Get vs. Delete, for example) just how dangerous this request is. You cannot do the same thing as easily on the SOAP side. Essentially, SOAP leaves this sort of security up to the application programmer, while REST uses facilities built into the infrastructure (network, firewall, etc.) to do this policing.

So What Should You Do?

That's the real question, isn't it? Nobody really cares what the differences are; they just want to know which one to use. Because there's always a correct answer, right?

But that's not always the case. And this is one of those cases. Both methods are solid, and both have their advantages, but in a world that was once totally dominated by SOAP, REST is steadily gaining ground.

So take a look at your web apps, or consider this when you build your first: are you RESTful?


David Shirey

David Shirey is president of Shirey Consulting Services, providing technical and business consulting services for the IBM i world. Among the services provided are IBM i technical support, including application design and programming services, ERP installation and support, and EDI setup and maintenance. With experience in a wide range of industries (food and beverage to electronics to hard manufacturing to drugs--the legal kind--to medical devices to fulfillment houses) and a wide range of business sizes served (from very large, like Fresh Express, to much smaller, like Labconco), SCS has the knowledge and experience to assist with your technical or business issues. You may contact Dave by email at This email address is being protected from spambots. You need JavaScript enabled to view it. or by phone at (616) 304-2466.

MC Press books written by David Shirey available now on the MC Press Bookstore.

21st Century RPG: /Free, ILE, and MVC 21st Century RPG: /Free, ILE, and MVC
Boost your productivity, modernize your applications, and upgrade your skills with these powerful coding methods.
List Price $69.95

Now On Sale



Support MC Press Online

$0.00 Raised:

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: