I've heard a lot of buzz through the years about "Self Describing" web services and I'm curious what it means. I've flipped through the W3C standard and it doesn't really help.
I understand you can say "Give me this argument and call this functionality and I'll return something like this", but how is that actually helpful? How can software know what is relevant to a client given some context?
Can anyone give real world examples of this concept, and explain how it's better than some other alternative? Or maybe how useful/useless it is?
It's really designed as a standard for describing in a cross-platform cross-language manner an interface that a developer can use to develop a SOAP based way to exchange information with a web service.
Another alternative would be providing a library that provides a local interface to a blackbox communcation scheme, which is fraught with compatability/security issues.
Or providing documentation, which may be difficult to find, have compatibility issues, be out of date, or incomplete.
In short, it's very useful.
Related
I was asked this question in an interview and had no idea. And I still don't. I thought they were created for this purpose, not to replace something that already exists. Any thoughts?
In oversimplified terms web services 'replaced' older RPC technologies like COM+ and CORBA
CORBA might be what the interviewer had expected you to answer. Or maybe RMI for java2java communication.
Probably the interviewer wanted to name some particular term but they improved the way different applications and systems communicate with each other.
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.
I'm creating a design document for a security subsystem, to be written in C++. I've created a class diagram and sequence diagrams for the major use cases. I've also specified the public attributes, associations and methods for each of the classes. But, I haven't drilled the method definitions down to the C++ level yet. Since I'm new to C++ , as is the other developer, I wonder if it might not make sense go ahead and specify to this level. Thoughts?
edit: Wow - completely against, unanimous. I was thinking about, for example, the whole business about specifying const vs. non-const, passing references, handling default constructor and assigns, and so forth. I do believe it's been quite helpful to spec this out to this level of detail so far. I definitely have gotten a clearer idea of how the system will work. Maybe if I just do a few methods, as an example, before diving into the code?
I wouldn't recommend going to this level, but then again you've already gone past where I would go in a design specification. My personal feeling is that putting a lot of effort into detailed design up-front is going to be wasted as you find out in developing code that your guesses as to how the code will work are wrong. I would stick with a high-level design and think about using TDD (test driven development) to guide the low-level design and implementation.
I would say it makes no sense at all, and that you have gone too far already. If you are new to C++ you are in no position to write a detailed design document for a C++ project. I would recommend you try to implement what you already have in C++, learn by the inevitable mistakes (like public attributes) and then go back and revise it.
Since you're new, it probably makes sense not to drill down.
Reason: You're still figuring out the language and how things are best structured. That means you'll make mistakes initially and you'll want to correct them without constantly updating the documentation.
It really depends on who the design document is targeted at. If it's for a boss who is non-technical, then you are good with what you have.
If it's for yourself, then you are using the tool to help you, so you decide. I create method level design docs when I am creating a project, but it's at a high level so I can figure out what the features of the various classes should be. I've found that across languages, the primary functionalities of a class have little to do with the programming language we are working in. Some of the internal details and functions required certainly vary due to the chosen language, but those are implementation details that I don't bother with during the design phase.
It certainly helps me to know that for instance an authorization class might have an authenticate function that takes a User object as a parameter. I don't really care during design that I might need an internal string md5 function wrapper to accomplish some specific goal. I find out about that while coding.
The goal of initial design is to get organized so you can make progress with clarity and forethought rather than tearing out and reimplementing the same function 4 times because you forgot some scenario due to not planning.
EDIT: I work in PHP a lot, and I actually use PhpDoc to do some of the design docs, by simply writing the method signature with no implementation, then putting a detailed description of what the method should do in the method header comments. This helps anyone that is using my class in the future, because the design IS the documentation. I can also change the documentation if I do need to make some alterations while coding.
I work in php4 a lot, so I don't get to use interfaces. In php5, I create the interface, then implement it elsewhere.
The best way to specify how the code should actually fit together is in code. The design document is for other things that are not easily expressed in code. You should use it for describing the actual need the program fills, How it interacts with users, what the constraints are in terms of hardware and operating systems. Certainly describe the overall architecture of your application in a design document, but, for instance, the API should actually be described in the code that exposes the API.
You have already gone far enough with the documentation part. As you still a beginner in C++, when you would understand the language, you might want to change the structure of your program. Then you would have to do changes in the documentation. I would suggest that you have already gone too far with the documentation. No need to drill more into it
Like everyone else says, you've gone way past where you need to go with the design. Do you have a good set of requirements to the simple true/false statement level that you derived that design from? You can design all day long, but if you don't have requirements that simply say WHAT you're going to do, it doesn't matter how good your design is.
I'm implementing an SOA at a large company, and I'm not sure which web service specifications (WS-*) actually make sense to implement. At a minimum, I'm looking at WS-Addressing, WS-Security, WS-Eventing, and WS-ReliableMessaging. However, there are several other standards that look interesting, but I don't know which ones are widely adapted. I don't want to implement a standard (and force all the developers to follow them) if they're not mature or necessary.
EDIT:
I'm asking this question not about a specific situation, but in general. There are quite a few WS-* standards that don't seem to have a lot of practical use (at least to me), so I'm really curious about which ones are widely used.
Thanks for your help!
KA
WS-Adressing is widely used, and quite useful. For WS-Security, consider the set of mechanisms you'll need (based on your usage scenarios).
Only SOAP is widely adopted. If you care about reach, going beyond WS-Security and WS-Addressing is asking for trouble (even WS-Security can be hard for a lot of people). If you are creating services for internal use in a large company, then I wouldn't worry as much. Something like WCF would allow you to provide endpoints with different bindings for a wide range of consumers without writing any additional code.
There are two types of web services : REST and SOAP. They represent different protocols of sending data over the internet.
SOA is an acronym standing for Service Oriented Architecture. It is a way of architecturing your system using multiplet tiers (applications) one atop the other. Web services, mostly soap based are used to implement this archtecture, but they are not the only way.
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".