The web service endpoint usually is defined in an early stage of a project. Since it follows the "contract first" principle, it shouldn't be changed after communicated to client systems.
Therefore, it is vital to label the web service in a good way.
How would you label web services?
e.g.
http://my.domain.com/businessProcess/services/concreteServiceName
Other ideas?
See this question as a poll... Feel free to vote for the best idea.
We decide on names by talking to the developers, business guys, and support guys. We formed a committee called the "interface control committee", and we approach it kind of like you described in the question. We want service names to be descriptive, reflect the processes they support, and fit the needs of the technical and business stakeholders.
When we have ICC meetings, we also talk about schemas and how they should be developed. The business guys are key in this as well since they know what data they want to expose and why.
KA
I would include a version number in the URLs.
Related
I am developing a SOAP interface and am having trouble deciding what to name the endpoint address.
Options:
- {soap,api,service,???}.foo.com.au
- www.foo.com.au/{soap,api,service,???}
What are the typical names that a SOAP service gets?
I would use www.foo.com.au/soap, mostly because it's an easy way to tell people that it's a SOAP service, and if you want to add a REST service later, you can use www.foo.com.au/rest
Keep in mind, in practice, all solutions are technically equivalent. The benefits of one naming system over another are only at the ease or understanding what the URLs are about (for humans), or maintainability, really. So, if you are searching for a standard we can tell, at best:
If you have a big company with lots of applications, go for the http://api.company.com/application/rest and/or http://api.company.com/application/soap approach
Reason: you can separate, right from the start (networkwise) the web service servers (http://api.srv.com/app) from the human web browsing servers (http://www.srv.com/app).
All applications have one big root "meeting" point (the root URL api.company.com), so if anyone wonders what is company-wide available, just check http://api.company.com and it can list all services available.
If your setup is not that big, it is probably not worth the trouble, so don't fear using the www.. But keep in mind it's best to use at least a different context, such as api/, so that anyone knows right off the bat a service URL is about a web service(!): http://www.company.com/application/api/rest / http://www.company.com/application/api/soap
Note: It's also common to use service, although api seems to be somewhat better descriptive (api.something.com leaves no doubt about what that page is about).
Some examples (as you can see, there is really no global standard):
Google's search API: http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=test
Twitter's search API: http://search.twitter.com/search.json?q=w00t
Facebook' Graph API: http://graph.facebook.com
Facebook' Dialog API: http://www.facebook.com/dialog (see, no standard even within facebook!)
Weather Gov SOAP forecast: http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl
Buy many seem to keep the good ol' company-wide APIs "meeting points":
http://developers.google.com
http://developers.facebook.com
http://dev.twitter.com
I have been fighting with this for a while now. I need to prototype SOA, and with it, the registry. I have been fiddling with jUDDIv3 on JBoss SOA Platform 5, but there don't appear to be any tools that allow me to publish to a v3 jUDDI registry. See my related questions here and here.
I realize after reading comments on those questions, and some articles on the internet (like this one) that UDDI is failing or dead, however my organization has some legacy tech we need to work with.
Also, my supervisor (I'm an intern) is adamant about sticking to standards. In principle, I agree with this, but perhaps a dead standard really isn't a much of a standard if nobody uses it.
In short, I need to provide the registry component of Service Oriented Architecture. It probably needs to be UDDI, so that it fits with the legacy tech, and satisfies the standard. Whatever the solution, it would be best if there were tools available that allow me to publish web services to that registry.
This problem has dragged on much longer than I would have liked. Any small piece of advice is really appreciated.
You may use WS-Discovery. WS-Discovery is a standard protocol for discovering services and service endpoints. This enables service clients to search for services based on a given criteria and bind with the discovered services. There are tow modes of WS-Discovery,
ad-hoc - servers advertise the services they have using a UDP multicast protocol
managed mode - servers and clients use an intermediary known as the discovery proxy for all service discovery purposes.
You can simply try this out with WSO2 Platform (free and open source under apache2 license). Please follow [1] to see a simple scenario of WS-Discovery in managed mode.
[1] http://charithaka.blogspot.com/2010/04/ws-discovery-with-wso2-carbon.html
Web services and web APIs have managed to increase the accessibility of the information stored and catalogued on the internet. They have also opened up a vast array of enterprise power functionality for smaller thin client applications.
By taping into these services developers can provide functionality that would have taken them months perhaps years to set up. They can combine them into single applications that make life generally easier for its users.
Whether displaying information about the music being played, finding items of interest in the locale of the user or just simply tweeting and blogging from the same application - the possibilities are growing everyday.
I want to know about the most interesting or useful services that are out there, especially ones that most of us may not have heard about yet. Do you maintain an API or service? or do you have a clever mash up that provides even more benefits than the originals?
YQL - Yahoo provide a tool that lets you query many different API's across the web, even for sites that don't provide an API as such.
From the site:
The Yahoo! Query Language is an
expressive SQL-like language that lets
you query, filter, and join data
across Web services.
...
With YQL, developers can access and
shape data across the Internet through
one simple language, eliminating the
need to learn how to call different
APIs.
The World Bank API is pretty cool. Google uses it in search results. My favourite implementations are the cartograms at worldmapper.
(source: worldmapper.org)
It's very niche, but I happen to think the OpenCongress API is amazing.
Less niche: Google Translate has an API which will guess the language of something. You'd be AMAZED how frequently this comes in handy (even though it's not as tweakable as you'd like and is not trained on small samples).
I was just about to have a stab at using the SoundCloud API
I know many people who already use for sharing their musical masterpieces and its a pretty good site. Hopefully the api will be as well!
I like the RESTful API for weather.com. It's free and very useful for the new age of location-aware apps: https://registration.weather.com/ursa/xmloap/step1
It does require registration, but they don't spam you or anything - it's just to provide you a key to use the API.
Ah yes - here's another one I've been meaning to check out but haven't tried yet
The BBC offer a bunch of apis/feeds that look very promising
http://ideas.welcomebackstage.com/data
They include apis for accessing schedule data for both TV and Radio listings along with all kinds of news searches. It even looks like they'll be offering some sort of geo-location service soon so it will be interesting to see what that has to offer
Another interesting one for liberal brits! ;)
The Guardian news paper have their own api
http://www.guardian.co.uk/open-platform
MuiscBrainz
Excellent service for music mashups.
Not so many knows that Last.FM initial database was scraped from this service.
The United States Postal Service offers a web service that does address standardization. Quite useful in reducing clutter and cleaning data before it gets put into your database.
Currently inside my organization we are trying to come up w/ some conventions for a pilot SOA project. At first glance we thought it would be best to force users of the service to use the business service w/out direct access to any data endpoints .. but are there specific scenarios where this is not true or it might be "valid" for developers to have access to specific data endpoints outside of a service?
I always fear that if we open this up, it will actually hurt reuse because everyone will just "re-invent" similar business services using the same back-end data as it's available and would be "in theory .. easier" to just write a new business service rather than ask "what does this other service do that uses my database?"
Because even if the service is almost a direct pass through to the database we would have the ability to apply rules that would save developers time and ultimately the business money.
Thoughts?
Wouldn't your webservice just be a thin wrapper for your business layer anyway? Your service layer probably shouldn't have anything more than your business layer besides some dumbed-down DTOs perhaps. Then noone is asking "what does this other service do that uses my database?" because it isn't using your db, it is using your BL.
You're waving a red flag when you describe "forcing" users to do anything. Maybe you can think about your question and rephrase it in terms something like "enable" users, because this should be the starting point for your decision, and SOA offers advantages and disadvantages for different UI strategies.
If you are going to start the development of an API for your web application. Is there any kind of guidelines, best practices or standard to build web services. I have seen a few discussions in this topic and I will like to get more information.
At least get pointers on where to get the information.
Thanks in advance.
There exists a wide variety and latitude regarding "web services". I find it useful to make explicit note of what we are talking about:
web = transported over HTTP(S)
service = remote procedure call (RPC)
Note that the HTTP(S) portion of this merely specifies the transport medium, but not the content. Also note that the RPC portion of this merely specifies the behavior (essentially invoking remotely a named function with arguments that returns a result) but not the content.
A critical question that arises is whether you control both sides of the communication. If so, but especially if not, you need to be concerned about interoperability.
SOAP is a standard for implementing a web service that specifies using specificly-formatted XML for the content of the request and response. It is VERY heavy, and there are still problems with interoperability across various implementations.
There are lots of custom implementations, most of which are lighter, but you will almost certainly have interoperability issues.
Since any form of content can potentially be used to achieve a web service, I recommend picking something that is able to handle complex content (to varying degrees), standardized, lightweight, and robust.
I am recently leaning towards JSON for the content format. I recommend considering the same, especially if you are considering implementing AJAX.
Best wishes.
API 101
I am pasting this URL as a close approximation of the possible answer. Since I did not get any other answer, I think this is as close as it gets.
I will like to have more detail best practice outline, if someone find something better, let me know to mark their answer as accepted.
If you could answer some of these questions, you might get a more satisfactory answer.
who is the audience that will be consuming the the service?
What types of client technologies will be consuming the service
what assumptions/restrictions can you put on them (platforms, tooling, skill
set)?
How broad is you API - how many methods will it expose?
Is security a consideration - how secure do you need to be?
Do you need to support transactions?