Understanding the difference between REST & XML based api's

[API Dev]

Hi,

I am trying to understand the difference between REST api's and XML based HTTP api's. An example of the XML based web api that we are looking at is Intacct. I am able to make api calls to these web service but I don't quite follow the structure of the api. 

The api endpoint url is - https://api.intacct.com/ia/xml/xmlgw.phtml . It accepts the authentication details through the HTTP POST request body. The body also includes application request details. These details need to be passed in a specific format in the body. i.e. xmlrequest = <request>....</request>. 

I have a few questions

1. Does such an api qualify to be called as a REST api? The fact that the api call succeeds through standard REST clients like postman, I am kind of confused if they could be termed as REST api's. In my understanding it violates some of the REST principles including
   1. Using POST request to fetch data from the server
   2. URL format does not include resource names
   3. Authentication details accepted as part of the request body instead of the authentication header parameter
2. What category do such api's fall under if not REST? Would it be right to call them as XML based api's? If so, what are the standards for defining such XML based api's?

Thanks

[Eric Johnson]

It sounds to me like you've already answered your question.

REST, as an architecture, is mostly agnostic about the media-type of the payloads being passed back and forth. If, everywhere, you substitute "BLARG" for "XML", you can probably see pretty quickly that your question has little to do with XML, per-se.

On Monday, June 5, 2017 at 2:28:07 AM UTC-7, API Dev wrote:

Hi,

I am trying to understand the difference between REST api's and XML based HTTP api's. An example of the XML based web api that we are looking at is Intacct. I am able to make api calls to these web service but I don't quite follow the structure of the api. 

The api endpoint url is - https://api.intacct.com/ia/xml/xmlgw.phtml . It accepts the authentication details through the HTTP POST request body. The body also includes application request details. These details need to be passed in a specific format in the body. i.e. xmlrequest = <request>....</request>. 

Even in a REST-ful implementation, it is sometimes necessary to use the "POST" method to retrieve resources (perhaps the criteria for what is being received is structured or difficult to capture in a set of query parameters). Using POST isn't disqualifying, but you don't mention anything about use of "GET" wherever possible, so that is a strong indication of a non-REST-ful implementation. Specifically, it sounds like RPC over HTTP.

 

I have a few questions

1. Does such an api qualify to be called as a REST api? The fact that the api call succeeds through standard REST clients like postman, I am kind of confused if they could be termed as REST api's. In my understanding it violates some of the REST principles including
   1. Using POST request to fetch data from the server

See comment above. 

1. 1. URL format does not include resource names

Indicates that the design is not oriented around resources. Difficult to tell from a single example.

1. 1. Authentication details accepted as part of the request body instead of the authentication header parameter

Authentication is a very tricky beast. I would not use the particular choice of authentication as a way to distinguish a REST-ful design from something else. However, if authentication information must ALWAYS be sent as part of the body of a request, that automatically means that GET requests never get used, and thus not a REST-ful design.

1. What category do such api's fall under if not REST? Would it be right to call them as XML based api's? If so, what are the standards for defining such XML based api's?

RPC over HTTP.

Eric

[sune jakobsson]

The main difference is that a XML endpoint could respond with a WSDL file, so that you could build and validate the parameters fully.

REST itself does not mandate a fixed format of the data.

Sune

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+unsubscribe@googlegroups.com.
Visit this group at https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[API Dev]

@Sune - Ok. In the api that I am looking at, it does not return a wsdl for data validation. The POST body XML content though accepts one of the tags as the dtd version. This could be used by the server for request body validation.

@Eric, I appreciate your detailed reply. I read a bit about XML RPC based HTTP api's and other api from Intacct. 

Using POST isn't disqualifying, but you don't mention anything about use of "GET" wherever possible, so that is a strong indication of a non-REST-ful implementation. Specifically, it sounds like RPC over HTTP

However, if authentication information must ALWAYS be sent as part of the body of a request, that automatically means that GET requests never get used, and thus not a REST-ful design.

Yes, GET is never used. The API provider exposes just one POST api. The body content controls what functions are called on the server.  There are various functions for CRUD operations. Below is the format of the request body.

  

 So as you rightly mentioned, this api seems to be RPC based HTTP api and not a REST based api. I have a follow up comment though

that automatically means that GET requests never get used, and thus not a REST-ful design

Why are "GET" requests an important factor in knowing if the API is RESTful?

Thanks! 

To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.

[Johan Groenen]

https://www.soapui.org/testing-dojo/world-of-api-testing/soap-vs--rest-challenges.html

Op maandag 5 juni 2017 11:28:07 UTC+2 schreef API Dev:

[Johan Groenen]

http://spf13.com/post/soap-vs-rest

Op maandag 5 juni 2017 11:28:07 UTC+2 schreef API Dev:

Hi,

[Eric Johnson]

On Mon, Jun 5, 2017 at 11:40 PM, API Dev <amit...@gmail.com> wrote:

Why are "GET" requests an important factor in knowing if the API is RESTful?

As per the HTTP 1.1 RFC, a "GET" operation is supposed to be "safe". It doesn't "do" anything. You can issue it as many times as you want (absent other calls), and you'll get a result with the exact same meaning. (This doesn't mean the exact same bits - https://www.nytimes.com always gives you "today's news").

"GET" is also idempotent. If the only verb in use is "POST", then nothing in the API is idempotent. Safe and idempotent request results can be cached on the client (or anywhere in between). Without that ability to cache, you cannot really get to the "T" part of REST ("transfer")

Proper use of "GET", with caching enabled, also forces the implementation to define resources that can be got, that is the "RE" part of REST ("REpresentation").

Eric