ArcGIS Server REST API 101 (Part I)
This article is the first in a series exploring the REST API for ArcGIS Server. Although only released for a few months, developer feedback for the new API seems to be very positive. In this series I’ll describe what REST is, how it’s used with ArcGIS Server 9.3, benefits/drawbacks, etc. In later articles I’ll discuss some alternative uses of the API and how to implement them.
Moving to REST with ArcGIS Server
The addition of the REST API to ArcGIS Server at 9.3 was welcomed by developers who knew the power and simplicity it would bring to developing applications, but for many developers and managers the benefits weren’t immediately apparent. If you’re used to developing applications with the Web ADF and are comfortable with ArcObjects, then developing with the REST API will be like a walk in the park. If you’re like me, just reading an ArcObjects model diagram is enough to induce headaches. To ESRI’s credit, they recognized the need for a simpler, faster way to build applications for ArcGIS Server. The REST API is not a panacea for all situations, but I think it provides a sweet spot that will cover many clients’ needs.
Intro to REST
This wikipedia article on REST provides a good jumping off point to learn more, so I won’t bore you with the details. But it boils down to this: the internet is a collection of resources in many different formats (HTML, PDF, XML, audio/video, etc.). Each resource has a unique location on the internet represented by a URI.
DIGRESSION WARNING… “But wait, didn’t you mean URL?” Technically, no. A URL is a type of URI. You know that little string you type into your browser’s address bar before a web address, “http://?” That specifies the URI protocol to use. You’re familiar with the other ones too: ftp://, mailto:, etc. While the AGS REST API only uses URLs, the generic REST architecture refers to URIs. So, to be consistent in this article I’ll use URI.
The idea is to use the fact that all resources have these globally unique URIs as a way for machines to exchange a document’s contents (or “Representation”). And within those representations you can link to other resource representations. Sound familiar yet? Yep, it’s the way the web works. Resources may be represented as hypertext documents (HTML) that contain links to other HTML documents, ad infinitum. The AGS REST API works the same way.
Imagine you’re at a crowded IT conference mingling with people. Protocol suggests that you shake hands with people when you introduce yourself (http:// in our example). When you reach out and take their business card, you’re using an HTTP GET request on that business card resource. The you move on to the next person…rinse and repeat. And those people do the same thing with other business card resources.
Here’s a an example from the AGS REST API. This URL, http://server.arcgisonline.com/arcgis/rest/services is an HTML representation of an ArcGIS Online REST service. Now try this link: http://server.arcgisonline.com/arcgis/rest/services?f=pjson. This is the same data, sent back as a JSON representation. Humans can easily understand the HTML representation and machines can use the JSON representation.
While this is a greatly simplified explanation of REST, hopefully you now have a better understanding of what it means, and if you’re a manager you’ll know what the hubub is all about when you hear your developers talking about it.
What does this mean for GIS?
The question you might be thinking is “That sounds nice, but what does it have to do with GIS?” Remember those representations from earlier (HTML, PDF, etc.)? GIS data also can be represented by those formats. A REST interface to GIS data can open up a wealth of possibilities for application development and make your data more accessible to the web at-large (e.g. search engines).
For developers, REST provides a cleaner separation between the front-end and back-end. Your front-end application code doesn’t need to speak in a GIS-specific API language (ArcObjects) because the REST API handles the GIS operations for you. In fact, you could know very little about GIS to take advantage of REST-based GIS resources. You can be up and running quickly with only a basic knowledge of REST, Javascript and HTML.
The ArcGIS Server REST API (and the accompanying Flex and Javascript APIs) have the potential to dramatically reduce the development and maintenance costs of building applications. And this will make developers, managers and clients happy campers.
Web ADF vs. Flex/Javascript
If it’s not already apparent, choosing the REST API means choosing either the Flex or Javascript application APIs. The Web ADF provides the standard, “out-of-the-box” scenario for most organizations, but there are trade-offs you should consider.
As I mentioned earlier, applications built upon the REST API have a sweet spot that may not work for every situation. In particular, if feature editing is critical to your application you’ll have to stick with the Web ADF (and thus ArcObjects). Currently, the REST API does not support HTTP POST and PUT commands which would support editing resources. Hopefully that will change in the future.
For now, the biggest reason I see for sticking with the Web ADF for development is to support feature editing. Another benefit of the Web ADF is the pre-made application template which can get you started quickly…as long as you don’t mind your application looking like every other application on the planet. As soon as you start customizing the look and feel, your costs will increase. While ESRI doesn’t provide “official” Flex/Javascript application templates, there are some floating around on the ArcScripts website. A downside of the Web ADF is that licensing may be a concern. The Web ADF runtime requires a license on any server on which it runs, so if you deploy in a multiple server environment this will increase your costs. The Flex and Javascript APIs are entirely browser-based, so there is no extra licensing fee. This means that you can deploy a Flex/Javascript application on multiple standard web servers apart from the ArcGIS Server and not incur extra licensing costs.
For anyone reading this article, feel free to share your thoughts on how you choose your application APIs. The good news is that ESRI is responding to their community by providing more choices for us.
Next time we’ll break down the specifics of the ArcGIS Server REST API and how it works.