we are currently thinking about how to design an interface for other systems.
My co-worker would like to implement a generic interface (for e.g. doIt(JSONArray)) where you put the desired information you would like to do inside a JSONObject, so that calls would e.g. look like this:
doIt('{"method":"getInformation", "id":"1234", "detailLevel": "2"}')
doIt('{"method":"getEmployeeInfo", "EmployeeId":"4567", "company": "Acme Inc."}')
(i used ' and " in this example just for demonstration purposes. I know that i had to escape the " in the real system).
This method will then be accessable via http, so that i would like http://mysite/doIt?parm={JSONObject}
My approach is to use different interfaces with their respective parameters so that I would have a getInformation(1234,2) and a getEmployeeInfo(4567,"Acme Inc.") interface. So for access via http my scheme would look like: http://mysite/getInformation?id=1234&detailLevel=2 and http://mysite/getEmployeeInfo?employeeId=4567&company=acmeinc.
For the clients accessing our service we want to provide special libraries that encapsulate the bevahiour. E.g. there will a client java-lib which translates a client-call getEmployeeInfo(..) either to
http://mysite/doIt?parm={'{"method":"getEmployeeInfo", "EmployeeId":"4567", "company": "Acme Inc."}'}
or to
http://mysite/getEmployeeInfo?employeeId=4567&company=acmeinc.
and then return the result.
So for clients it will be completely transparent how the backend works if they use the library which handles the "translation".
What do you think are the pros and cons of each idea? I like my approach better because it looks "cleaner". But that is just a feeling which is difficult to argue about. Perhaps you can give me (or him) some thoughts about the design and also touch areas (scalability, security,...) or provide useful links about this matter
I'd probably vote for the JSON solution, even if they are more or less equivalent. (Both easily extendable, standard, future-proof solutions.)
The reasons for choosing JSON:
There are a plethora of different libraries for different platforms that help you build correct objects, check that the string data is valid, etc.
Unmarshalling of JSON data into objects. Some libraries (for example Gson) can automatically marshal and unmarshal JSON into objects. Saves you from writing your own code, and you get the benefit of using code that has been tested by others.
Support for new interfaces. Suppose that you change your transport method to sockets, ftp(!) or whatever. You could still send the JSON objects to you backend using another transport.
I realize this question is old, but I think the answers here would guide developers down the wrong path.
In my experience you should always lean towards the more specific methods. Generic methods are difficult to test, difficult to wrap your head around and provide no (or minimal) IDE/compiler support. Such an api you are describing does not tell the user anything about what it will do.
Your own suggested api design is much better.
That being said, its a balancing act.
The JSON solution could be better because you can send complex object easier
But here it's just a little syntax detail, let the boss choose (or do a vote) and build your software.
Related
I'm designing a new API and I'm struggling with some decisions. I've read tons of blogs on SOAP vs REST and I used the popular APIs (Paypal, Amazon, etc.) as my guidelines.
I ended up with 2 endpoints in my API: one for SOAP and one for REST (XML). The SOAP one looks pretty good, but the XML interface looks somewhat strange. I'm calling it "strange" because I ended up with namespaces in some of my tags. For example:
[sample1]
<EnvelopeRequest xmlns:c1='http://foobar/CarrierX'>
<Weight>1.0</Weight>
<PostmarkDate>5/3/2013</PostmarkDate>
<c1:ShippingMethod>Ground</c1:ShippingMethod>
<c1:Notification>a#b.com</c1:Notification>
</EnvelopeRequest>
[sample2]
<EnvelopeRequest xmlns:cs='http://foobar/SpecialCarrier'>
<Weight>1.0</Weight>
<PostmarkDate>5/3/2013</PostmarkDate>
<cs:Shape>Flat</cs:Shape>
</EnvelopeRequest>
The reason the XML interface has namespaces is because it is auto-generated from the class definition (which has some inheritance). We are using WCF btw. That works just fine for SOAP (the WSDL is derived from the same class), because SOAP hides all the ugliness in the client proxies. However, after looking at many REST/XML services, I don't think I've seen namespaces being used too often. This also kinda scares me because I'm thinking that I would love to have a JSON interface in the near future, and JSON doesn't support namespaces.
My decision to make the API SOAP friendly came from the fact that many of our customers use Enterprise solutions which thrive on SOAP. But lately, with the growing popularity of Python and Ruby, which new clients seem to adopt more often, I'm starting to second guess my initial decision. The main thing that bothers me is the namespaces in the XML interface, but is it really an issue? Are namespaces in a REST/XML API such a big no-no that I should change my design?
If I do change my design, then my (2 previous) requests would look like so:
[sample1]
<EnvelopeRequest>
<Weight>1.0</Weight>
<PostmarkDate>5/3/2013</PostmarkDate>
<CarrierX>
<ShippingMethod>Ground</ShippingMethod>
<Notification>a#b.com</Notification>
</CarrierX>
</EnvelopeRequest>
[sample2]
<EnvelopeRequest>
<Weight>1.0</Weight>
<PostmarkDate>5/3/2013</PostmarkDate>
<SpecialCarrier>
<Shape>Flat</Shape>
</SpecialCarrier>
</EnvelopeRequest>
And yes, this would allow me to have a JSON interface in the future.
Removing namespaces would be a problem if by doing so you create the possibility of ambiguity in a given message. Is it possible for someone somewhere to create an EnvelopeRequest message with a Shape element that might be interpreted (by code or by people reading the message) in more than one way? The reason to introduce namespaces is to preclude this possibility. Tools like WCF's auto-generator are not able to answer this question in the general case so they err on the side of caution.
Only you can know the set of possible valid messages. In my experience, it's usually preferable to remove namespaces for the sake of not confusing your users/clients. There are a few reasons why I might change that preference:
I expect my message format to be used widely and intermixed with other formats. (A good example is the Atom syndication format)
I'm using someone else's widely used (and namespaced) format and planning to intermix it with my own (e.g. embedding XHTML inside my message).
I expect to embed a message of a given format inside a message of the same format (e.g. XSLT stylesheets that generate XSLT stylesheets).
In that latter case, you might find it convenient (though not absolutely necessary) to use namespaces to separate the inner message from the message that is carrying it by using different prefixes. I don't think any of these cases apply very often.
I would ponder why you have namespace in the first place, those are some strange payloads.
But, disregarding that, no, the namespaces are not a big deal. Namespaces almost inevitably run afoul with XPath and XSL (since they tend to be namespace aware), but when consuming the document wholesale, a lot of times folks just ignore the namespace component completely, so in the end there's no difference.
I would clean up the namespaces for the sake of cleaning them up semantically, but not necessarily for the sake of the consumers. From a practical stand point, it's not that big a deal.
I have a RESTful service that exposes enums.
Should I expose them as localised strings, or plain integers?
My leaning is toward integers for easy conversion at the service end, but in that case the client needs to grab a list of localised strings from somewhere in order to know what the enums mean. Am I just creating extra steps for nothing?
There seems to be little information I can find about which is commonly done in RESTful APIs.
EDIT:
OK. Let's say I'm writing a website that stores information about people's pets. I could have an AnimalType enum
0 Dog
1 Cat
2 Rabbit
etc.
When people grab a particular pet resource, say /pets/1, I can either provide a meaningful localised string for the animal type, or just provide the ID and force them to do another look up via a /pets/types resource.
Or should I provide both?
I guess you should think in therms of consistent RESTful API you want to expose to your clients.
Wheter you yourself use enums in your code or not is an implementation detail.
Wheter your client will use enums in his implementation you neither know nor should that bother you because that's just different level of abstraction.
API design first, implementation follows.
If you provide a bit more insight of what kind of information you want to return to your client using these enums I could give more straight answer.
For now I guess if integer ids and string descriptions are relevant in describing information or state you want to return in call to your RESTful resource then you shuould return them both wrapped in a json or xml document.
If the intent is for the API consumer to use these values programmatically (i.e. make decisions based on them), I would go with UNlocalized strings (and make sure they are well-documented and stable). Enum values are not localized in local development frameworks and developers are used to dealing with this, not sure why a web API would be any different.
If the intent is for the API consumer to display these values to the user, I would go with localized strings.
If the intent is to be able to do both, I would go with UNlocalized strings (IDs), but consider providing a separate API endpoint/resource (or even an offline document) to map these IDs to localized strings.
And if for some reason you really care about message size (e.g. you have thousands of these things in a single message, and it's a mobile scenario), only then I would consider going with numeric IDs.
We currently have a number of C++/MFC applications that communicate with each other via DCOM. Now we will update the applications and also want to replace DCOM with something more modern, something that is easier to work with. But we do not know what. What do you think
Edit
The data exchanged is not something that may be of interest to others. It is only status information between the different parts of the program running on different computers.
there are many C++ messaging libraries, from the old ACE to new ones like Google's Protocol Buffers or Facebook's (now Apache's) Thrift or Cisco's Etch.
Currently I'm hearing good things about ZeroMq which might give you more than you are used to.
DCOM is nothing more than sugar-coating over a messenging system.
Any proper messenging system would do, and would allow you to actually spot where messages are exchanged (which may be important to localize point of failures/performance bottlenecks in waiting).
There are two typical ways to do so, nowadays:
A pure messenging system, for example using Google Protocol Buffers as the exchange format
A webservice (either full webservice in JSON or a REST API)
I've been doing lots of apps in both C++ and Java using REST and I'm pretty satisfied. Far from the complexity of CORBA and SOAP, REST is easy to implement and flexible. I had a bit of a learning curve to ged used to model things as CRUD, but now it seems even more intuitive that way.
Now, for the C++ side I don't use a specific REST library, just cURL and a XML parser (in my case, CPPDOM) because the C++ apps are only clients, and the servers are Java (using the Restlet framework). If you need one, there's another question here at SO that recommends:
Can anyone recommend a good C/C++ RESTful framework
I'd also mention my decision to use XML was arbitrary and I'm seriously considering to replace it with JSON. Unless you have a specific need for XML, JSON is simpler and lightweight. And the beauty of REST is that you could even support both, along with other representations, if you want to.
We're working now on the design of a new API for our product, which will be exposed via web services. We have a dispute whether we should use strict parameters with well defined types (my opinion) or strings that will contain XML in whatever structure needed. It is quite obvious that ideally using a strict signature is safer, and it will allow our users to use tools like wsdl2java. OTOH, our product is developing rapidly, and if the parameters of a service will have to be changed, using XML (passed as a string or anyType - not complex type, which is well defined type) will not require the change of the interface.
So, what I'm asking for is basically rule of thumb recommendations - would you prefer using strict types or flexible XML? Have you had any significant problems using either way?
Thanks,
Eran
I prefer using strict types. That gives you access to client tools that make that end of the job much easier. You also state that if the messaging changes, the string approach will not require changing the interface. Personally, I see this as a disadvantage, not an advantage. If the interface changes, you will know very quickly which clients need to be updated.
Strings containing XML is an extremely bad idea and asking for trouble. Use messages that have a defined schema.I had to rewrite significant portions of an app that used a lot of XML internally instead of types. It was horribly slow and impossible to figure out what was happening.
I have no experience with web services. Historically I've built client-server systems using proprietary communication protocols (even they happen to be XML). I just spent a few hours looking over Axis2 and it sent a shudder down my spine. The learning curve of WS scares me, and seeing all that XML surround so little functionality makes me wonder if it's worth the trouble.
How do you decide whether you need to use Web Services or a custom communication protocol? What are the advantages/disadvantages of each approach and what use-cases are they best suited for?
Please post a clear guideline, not an opinion piece :)
Build RESTful web APIs; then you get a lot of automatic caching and etc benefits that you don't get if you use other methods (SOAP, XML-RPC, etc)
See this post for more details
Another benefit is that if you build a RESTful API for your code to use, you can potentially let your users take advantage of it too - they often have uses for your product that you never dreamed of.
"Web Services" as defined by the W3C means using SOAP over HTTP. SOAP is severe overkill in most cases; it's only really appropriate (IMO) when you're making a public service available to the world, like an API for interacting with your website, for example.
Anything else (especially internal, private communications) rarely need anything more complex than XML-RPC. Only if performance is an issue should you consider a more condensed protocol; XML-RPC is so simple and widely-supported that the ease of development and debugging more than makes up for the performance loss of using bloaty ol' XML.
Remember that there are a number of frameworks out there that make programming web services very trivial stuff. In the VB / C# world .Net makes it a joy. I'm not really sure about specific frameworks for other languages but I am sure most have at least one.
The standardisation and simplicity of implementation and reuse of web services make them very attractive. As previously pointed out- yes, they make communications very verbose. If you are worried about this why not calculate how much data you actually will be trasmitting. chances are, with current network and internet speeds, it will be trivial - even with the XML overhead.
I would always use the custom data formats as a last resort and not a first. What widely used method you use it up to you but it's unlikely you would go wrong with Web Services model.
Maintainability and extensibility are the main benefits. The use of widely used technology your solution will be easier for someone else to understand plus you can use ready to roll libraries as consumers and providers.
I have recently broken my custom protocol habit. I am now using Apache on the server side and libCurl plus libxml2 to load and parse the XML on the client which is written in C++.
The server side can be either PHP or a CGI written in a more serious language. Depends what you want to do.
Webservices have the advantage of being somewhat standard, so it's possible for programs you've never heard of to use a webservice you wrote. Using HTTP can help them communicate over proxies and other network obstacles without any extra work from you. The XML, although rather verbose and ugly, is rather easier to read when debugging than binary data.
When you're transferring stuff over the network, it's unlikely that serialisation/deserialisation to xml will be the limiting factor in performance. It can be a bit of hassle, although a library to do it for you will help a lot.
SOAP and XML -- "all that XML surround so little functionality makes me wonder if it's worth the trouble."
Totally. SOAP is heavy-weight, and -- to a large extent -- a workaround to the need for static binding throughout the Java technology stack.
REST, on the other hand, is much lighter weight. Further, REST with JSON or REST with YAML is very lightweight, and very easy to implement. It builds right on top of the off-the shelf HTTP protocol.
REST requires you to define resources (named via URI's), and transactions based on the canonical CRUD rules (GET, POST, PUT and DELETE). Very simple and canonical.
In my personal (old cranky dude) opinion, web services should only be used as a way to make some of your internal information available to third parties (i.e. other companies, people outside your organization etc.). Of course, that is also the originally intended purpose of XML. :-)
If you have access to a direct connection with the databases containing the information your application needs - that is the way to go. It's faster and simpler - which in application development means "better" and "less buggy".