1

I have a proper SOA architecture, with web services defined with WSDL and responding to SOAP requests.
But this application has also an endpoint that responds to json request and replies in json format, so a little bit more like REST.

My goal is to transform this application into a sort of platform, exposing an API, and I have to understand all the best practices to build this API. My question is about the very first step: how can I define an API from such a hybrid architecture?

It is not REST, but it's excluded using SOAP for requests.
Is it still a webAPI? Is there any "classification" beside REST API? I am a bit confused, read everywhere but still don't get the main point of this.

Already read here: Difference between Web API and Web Service?

Improve this question
5
  • 2
    An API is not RESTful just because it happens to use JSON. There's no reason at all why a REST API couldn't use XML as its data format, for example. In any case, I'm not entirely sure I understand what problem you are trying to solve here.
    – yannis
    Commented Nov 18, 2015 at 16:26
  • 1
    I believe you are looking for swagger. See the classic petstore.swagger.io and its api petstore.swagger.io/v2/swagger.json
    – user40980
    Commented Nov 18, 2015 at 16:27
  • 1
    It's already an API. It doesn't stop becoming an API just because it contains different protocols.
    – Robert Harvey
    Commented Nov 18, 2015 at 16:31
  • 1
    Are you asking what to call your api? Are you asking how to build it? How to explain it to developers who will use it?
    – joshp
    Commented Nov 18, 2015 at 17:25
  • yes yannis, you're right. And for the others, maybe i didn't explain myself in the proper way. My question is about naming my API. Is it correct to call webAPI? i read that it is more used for proper REST API and this is not REST. I have 2 options: maintaining only json calls, then i think i can talk about webAPI; or maintain SOAP and json, so is it still correct to talk about webAPI? Yes, problem is about naming.
    – sissy
    Commented Nov 19, 2015 at 8:52

3 Answers 3

Reset to default
3

You have an API that uses HTTP, in my book that makes it a "web API". That's a completely generic term that implies nothing else.

REST and Web Service are two examples of web APIs. Yours isn't REST and only part of it is a SOAP Web Service.

I would describe it as "A web API that uses mostly SOAP but also has a more freeform endpoint that uses JSON requests and responses".

No need to overthink this stuff.

Improve this answer
1
  • Yes you're right. I've already been thinking too much to this formal stuff. Time to solve it. thank you
    – sissy
    Commented Nov 19, 2015 at 12:08
1

REST architecture recognizes that on a field-by-field basis, thereare ultimately only the C.R.U.D. operations that encapsulate ALL state definitions. This does "break" our so-called oldSchool ideas about transaction boundaries and all that stuff, but just because someone stood up and screamed the acronym "REST!!!!", we don't have to only do that.

Just because it's theoretically possible to decompose every object transfer between systems/components down to a REST-style field-based CRUD operation, doesn't mean we have to.

Improve this answer
1
  • You're right, it's just that reading all around everything seems is turning REST and wanting to be more sticky to the state of the art, one should be compliant to it in some way. But it's also true that is not compulsory
    – sissy
    Commented Nov 19, 2015 at 12:06
1

Is this for academia or for the work world?

In the work world, JSON is so much easier to parse than XML. For example, in the PHP language, JSON data seamlessly imports into an associative array (which is a data structure native to PHP and operated on by dozens of built-in PHP functions). XML, however, usually has to be parsed with special library functions which are more limited. And even then, iterating the nodes of an XML document is less intuitive.

SOAP has also proven to be a very picky protocol. I've seen multiple real-world occasions where different SOAP adapters didn't talk to one another successfully. There were lots of cryptic SOAP fault errors thrown. And deep inspection and tweaking of the SOAP messages led to inexplicable dead-ends.

I'm convinced that it's reasons like these that REST/JSON seems to be slowly replacing SOAP/XML as the preferred format and protocol for exchanging data out in the industry.

As for exact REST or SOAP theoretical specifications and how each API or vendor adheres to them in practice...don't ask. Theoretical specifications are for authors of computer science papers. Results are for people trying to deal with business challenges and put food on their table at the end of the day. The web has always been a kludge of half-baked, ill-fitting technologies.

If you can find a way to simply, easily, reliably, securely, and coherently exchange data...then you win. The simpler, the better.

Improve this answer
1
  • I like your point, you're totally right. This is a project for academia, using and industry platform, existing since several years. I have to give some guide lines on how to build this API and open it to the world of app developers. My question was about the naming concern, but you pointed out other issues i will have to take into consideration, like xml vs. json, so you're going even further, and helped me a lot.
    – sissy
    Commented Nov 19, 2015 at 12:05

Not the answer you're looking for? Browse other questions tagged or ask your own question.