As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 9 years ago.
I am planning on putting up a web service, or some other service exposed over the internet. I would like to create an API for applications to interact with this service. I would like the API to be usable in different languages, such as Java, C++, C#, or PHP. How can I maintain one code base for my API, but distribute nice packaged binaries for all these languages? Also, I may want to consider this could be cross platform as well.
Update 1
I'm early days on Web Services, but I
think one of the key points is that
lots of tooling supports the
implementation of clients based on the
description of the service like WDSL.
I've not delivered any client-side
software with anything I've done, I
expect any user to be able to build
their own clients suited to their
needs. --Brabster's Answer
I am not opposed to making it a straight web service then giving out a WSDL file. But what if I want the client API to do some logic, encryption, error checking or so on?
Update 2
As far as expecting the client that is
using your API to do anything, you
can't! There is nothing you will be
able to do to ensure that the consumer
of the API will do anything right.
That's why robust error handling is so
important. You must check and double
check any and everything that comes
from the client. You must always be
suspicious of it, and even assume that
it is malicious. There really is no
good way around that fact. --Ryan Guill's Answer
My original idea was to create a DLL or Assembly in .NET, then the client is making calls into this code that is running client side. This code may talk via any communications protocol back to the server, but my API would be running on their box. I guess REST does not really accomplish this. It seems like in REST everything is still an HTTP post. It is almost web services with out soap.
Update 3
I have accepted Ryan Guill's answer. I think the general idea is that I need to expose a network service of some sort, with the lowest barrier to the client. That way anyone can connect. Then just have all my code run on the server. That seems to be accepted as the only want to really achieve the platform and language independence I am after.
Thanks for all the input.
I would use a REST API, similar to the way Flickr's API works: http://flickr.com/services/api/
It is fairly simple to create and maintain, the biggest downsides are that it takes a lot of documentation (but pretty much any way you do an API will have this issue) and that robust error handling is a must.
But in my opinion, it's the best way to create an API that is the closest to cross platform/cross language.
More information here: http://www.xfront.com/REST-Web-Services.html
Update: The submitter added the following to the post:
I am not opposed to making it a straight web service then giving out a WSDL file. But what if I want the client API to do some logic, encryption, error checking or so on?
I personally do not like using SOAP (using a WSDL). There is a lot of inherent overhead to using SOAP, both on the server and the client. I think that is why you see more and more public API's being written using REST. It really lowers the barrier to entry to the lowest common denominator, allowing anything that can use basic HTTP (GET and POST (also PUT and DELETE for the "proper" way of doing it)) to use the API.
Some more examples of public API's written using REST: twitter, vimeo, Google
As far as expecting the client that is using your API to do anything, you can't! There is nothing you will be able to do to ensure that the consumer of the API will do anything right. That's why robust error handling is so important. You must check and double check any and everything that comes from the client. You must always be suspicious of it, and even assume that it is malicious. There really is no good way around that fact.
Update 2: the submitter added the following to the post:
My original idea was to create a DLL or Assembly in .NET, then the client is making calls into this code that is running client side. This code may talk via any communications protocol back to the server, but my API would be running on their box. I guess REST does not really accomplish this. It seems like in REST everything is still an HTTP post. It is almost web services with out soap.
You can certainly do this, but that is only going to work for .NET languages, meaning that your cross-platform and cross-language benefits are out the window. And still, in the end, are you really preventing anything? The developer is going to either use your remote API, or your local DLL or Assembly. Either way, he is going to have to know how to use it and use it right, otherwise you are going to throw an error. All you are really doing is changing where the errors get thrown from. Which may be important to you (if so, mention why) but really isn't changing anything in the equation.
But you are somewhat correct in saying REST is kind of like web-services without the SOAP. Technically REST is web-services too, its just that web-services have come to generally mean SOAP. It really is a different way of achieving the same thing. The biggest differences are though that it takes more programming and thought on your side (and potentially more programming on the client side) but you trade that for robustness, less overhead in both the consumer and the server, and the widest possible audience for the API. It really is the lowest common denominator.
I'm early days on Web Services, but I think one of the key points is that lots of tooling supports the implementation of clients based on the description of the service like WDSL.
I've not delivered any client-side software with anything I've done, I expect any user to be able to build their own clients suited to their needs.
If you check out the flickr API as suggested by one of your other answers, I don't think they supply client side code, other people have built and contributed client side stuff.
I suggest writing the API in the Haxe programming language so that the source code can be directly translated to all the programming languages you mentioned. The Haxe programming language can be translated (or "trans-compiled") to all of the programming languages that you mentioned in the original post, as well as a few others.
Simple answer, no.
Complex answer: create an API and compile it to a COM dll. Then, just build the wrapper code for the languages that can't handle that.
Simple answer #2, make the original service so trivial, or so universally acceptable, as to not require an API (I usually implemented this through server-side database polling. Ugly but any language that can access a database can utilize the program).
Related
APIs are getting more and more popular and are used by developers to ease the process of developing applications to multiple platforms AND allow them to give other developers the ability to integrate their application's functionality into their own applications.
I've used APIs countless times before, but I'm now at the stage of developing my own applications. And as a developer who strives to create multi-platform applications - I need to use an API.
I'm going to use the RESTful approach as it's recommended the most.
After reading and looking for some background information, I came across: REST API Tutorial (which is really good site!), I learned that APIs basically receive HTTP requests, and return data in JSON/XML format.
However, there were 2 questions left unanswered to me:
In what form do APIs come in? Are APIs actually files? a set of commands......?
How do I actually write APIs? I'm talking about the server-side, data-handling code, and not the application/language-specific code (for sending out HTTP requests etc...)
It'd be great if someone could help me and answer the questions above as I have zero experience with APIs.
Any help is appreciated - much thanks!!
Just a quick from-the-gut answer: They are whatever you want them to be!
Off the top of my head, I would define an API as requiring two main elements:
Some documentation which makes it quite clear how to use the logic your systems prvides
Some way to call those systems. That may be as simple as a web-site that accepts POST-messages, and checks them for certain variables and values in order to perform specific tasks.
In short, it should be entirely up to you. Just make sure you provide simple, clear and acurate documentation.
UPDATE, as an asnwer to the comment below:
That is how I interpret it, and it would seem that Wikipedia is more or less in agreement with me. PHP would be a perfect example: You could for instance create a PHP-file which processes a POST, and instead of outputting html, outputs XML with the resulting data needed. Then a third party app could POST to your PHP application, and receive and process the resulting XML.
Apis come as a response to a http request. It is a plain text response that u can use encoded via json or xml as you described.
There are a plenty of frameworks to help you develop and API.
In Ruby u can use grape or rais-api or even rails itself.
There is a lot more available, but this are the ones im most used to use.
I work at an IP camera company and we currently have an outdated CGI HTTP API interface. The CGIs are implemented in C.
I would like to learn and implement a new HTTP RESTful API so that the following type of things can be performed:
http://[ipaddr]/api/video/start
http://[ipaddr]/api/video/stop
I would like to write this RESTful API from the ground up in my spare time so I can learn this new skill.
I am very experienced in embedded C programming and Web technology front end (HTML, JS, CSS, etc), however, I would like to implement the link between the front end web UX and the application code (and/or web backend).
I would like advice on the current methods of implementing HTTP APIs. I really like to learn the 'right way' to do things before I start.
I have found that all the things I have seen such as OAuth, XAuth, REST, SOAP, implementation languages is a bit overwhelming!
Is there anyone on Stack Overflow that could provide a sensible path to learn these things? I'm very adept at self-learning but could just do with a few pointers in the right direction.
I would like to write whatever I can in C ideally as that would be the easiest way to get into the application code. However, if people recommend another language I'm happy to go with that if there are clear pros.
Get yourself a copy of Richardson and Ruby's RESTful Web Services (O'Reilly). They talk about how to design and implement RESTful services using several different technologies. It's so good you almost don't need anything else except RFC-2616 (HTTP 1.1) and Roy Fielding's original dissertation on REST.
There are a lot of great libraries to build on (depending on how much you want to learn directly). In the Java world, the Apache HTTP Client library is a good foundational layer. A REST framework like RESTlet automates much of the rest for you, making it relatively simple.
First, you've got to figure out what your webserver is going to be, something which is probably going to be driven by your choice of OS. Windows or Linux? Or something else?
If you're using Windows, you'll likely be using something like ASP.NET or WCF; there's good REST support in those, and you can easily find some good documentation. This will probably require implementation in a managed language, though, so expect a bit of learning curve from that.
If you're using Linux as your webserver, you'll probably want to use Apache as your webserver software, which would imply any number of different possibilities for server software; PHP, Python, etc. You can likely easily invoke C from those languages, although there are probably easier ways to do what you want than invoking C from there. Of course, Linux as a webserver gives you additional options for server software; you could always go with node.js and Express for your REST API; there's a bit of learning involved to do it well, but for blistering speed, it's hard to beat node.js.
start and stop are not resources but actions, and do not belong in a URL.
Instead you should use PUT or PATCH to send a boolean such as stream=true or stream=false to a URL like http://[ipaddr]/video (no need for /api/ either)
The client sends the new state, and the camera reacts. Once the state has been changed (video started or stopped) it responds with a 200, with the new state in the response body, or 204 with no response body. Or if the operation is lengthy, you can respond with 202 Accepted and no response body.
The same can be used to start and stop /audio streams.
For more info, please read http://weblogs.java.net/blog/mkarg/archive/2010/02/14/what-hateoas-actually-means
Most of the applications these days provide an API...be it twitter,gmail,fb and millions others.
I understand API Design can not be explained in just an answer but I would like some suggestions on how to get started with API design. Maybe some tutorial/book that makes an application and has some chapters on how to go about providing API's for it. I'm mostly a java developer (learning Groovy) but am open to other languages also, if it is easier to get started with API design in that language.
As a side note, before I was curious about the difference between an API and a webservice. But now as I understand it, webservice is just a form of an API
I don't have any great resources however, I want to stress how correct that API is Application Programing Interface, and is simply a mechanism for how you expose your application to be consumed by others. Be it from script, web service (soap or rest), Win32 API Style Calls....
About 10 years ago when we talked API it seemed like everyone felt like all APIs were like Win32, and that was it. One of the more interesting I've worked on was an API with a PICK based Management System. In this case we wrote an XML processor in PICK and were screen scraping XML back and forth over a telnet session.
The first thing you need to decide, is how do you want to expose your data. Are you going to expose over the web? Or is your application a desktop application? How I would structure an API for cross machine communication tends to be different then if the API is running in a single process or even on a single machine.
I would also start by writting a test client, You have to understand how your API will be used first and try to make it as simple as possible. If you dive right in with the implementation you might loose perspective and make assumptions that a client developer might not.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
Background:
I am taking a class at my university called "Software Constraints". In the first lectures we were learning how to build good APIs.
A good example we got of a really bad API function is the socket public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds); in C#. The function receives 3 lists of sockets, and destroys them making the user have to clone all the sockets before feeding them into the Select(). It also has a timeout (in microseconds) which is an int, that sets the maximum time the server can wait for a socket. The limits of this is +/-35 minutes (because it is an int).
Questions:
How do you define an API as
'bad'?
How do you define an
API as 'good'?
Points to consider:
Function names that are hard to remember.
Function parameters that are hard to understand.
Bad documentation.
Everything being so interconnected that if you need to change 1 line of code you will actually need to change hundreds of lines in other places.
Functions that destroy their arguments.
Bad scalability due to "hidden" complexity.
It's required from the user/dev to build wrappers around the API so that it can be used.
In API design I've always found this keynote very helpful:
How to Design a Good API and Why it Matters - by Joshua Bloch
Here's an excerpt, I'd recommend reading the whole thing / watching the video.
II. General Principles
API Should Do One Thing and Do it Well
API Should Be As Small As Possible But No Smaller
Implementation Should Not Impact API
Minimize Accessibility of Everything
Names Matter–API is a Little Language
Documentation Matters
Document Religiously
Consider Performance Consequences of API Design Decisions
Effects of API Design Decisions on Performance are Real and Permanent
API Must Coexist Peacefully with Platform
III. Class Design
Minimize Mutability
Subclass Only Where it Makes Sense
Design and Document for Inheritance or Else Prohibit it
IV. Method Design
Don't Make the Client Do Anything the Module Could Do
Don't Violate the Principle of Least Astonishment
Fail Fast - Report Errors as Soon as Possible After They Occur
Provide Programmatic Access to All Data Available in String Form
Overload With Care
Use Appropriate Parameter and Return Types
Use Consistent Parameter Ordering Across Methods
Avoid Long Parameter Lists
Avoid Return Values that Demand Exceptional Processing
You don't have to read the documentation to use it correctly.
The sign of an awesome API.
Many coding standards and longer documents and even books (Framework Design Guidelines) have been written on this topic, but much of this only helps at a fairly low level.
There is also a matter of taste. APIs may obey every rule in whatever rulebook, and still suck, due to slavish adherence to various in-vogue ideologies. A recent culprit is pattern-orientation, wherein Singleton Patterns (little more than initialized global variables) and Factory Patterns (a way of parameterizing construction, but often implemented when not needed) are overused. Lately, it's more likely that Inversion of Control (IoC) and associated explosion in the number of tiny interface types that adds redundant conceptual complexity to designs.
The best tutors for taste are imitation (reading lots of code and APIs, finding out what works and doesn't work), experience (making mistakes and learning from it) and thinking (don't just do what's fashionable for its own sake, think before you act).
Useful - it addresses a need that is not already met (or improves on existing ones)
Easy to explain - the basic understanding of what it does should be simple to grasp
Follows some object model of some problem domain or real-world. It uses constructs that make sense
Correct use of synchronous and asynchronous calls. (don't block for things that take time)
Good default behavior - where possible allow extensibility and tweaking, but provide defaults for all that is necessary for simple cases
Sample uses and working sample applications. This is probably most important of all.
Excellent documentation
Eat your own dog food (if applicable)
Keep it small or segment it so that it is not one huge polluted space. Keep functionality sets distinct and isolated with few if any dependencies.
There are more, but that is a good start
A good API has a semantic model close to the thing it describes.
For example, an API for creating and manipulating Excel spreadsheets would have classes like Workbook, Sheet, and Cell, with methods like Cell.SetValue(text) and Workbook.listSheets().
A good API allows the client to do pretty much everything they need to do, but doesn't require them to do a lot of mindless busy-work. Examples of "mindless busy work" would be initializing data structure fields, calling several routines in a sequence that never varies with no real custom code in between, etc.
The surest sign of a bad API is if your clients all want to wrap it with their own helper code. At the absolute least, your API should have provided that helper code. Most likely, it should have been designed to provide the higher level of abstraction the clients are rolling themselves on their own every time.
A bad API is one that is not used by its intended audience.
A good API is one that is used by its intended audience for the purpose for which it was designed.
A great API is one that is used by both its intended audience, for the its intended purpose, and an unintended audience for reasons unanticipated by its designers.
If Amazon publishes its API as both SOAP and REST, and the REST version wins out, that doesn't mean the underlying SOAP API was bad.
I'd imagine that the same will be true for you. You can read all you want about design and try your best, but the acid test will be use. Spend some time building in ways to get feedback on what works and what doesn't and be prepared to refactor as needed to make it better.
A good API is one that makes simple things simple (minimum boilerplate and learning curve to do the most common things) and complicated things possible (maximum flexibility, as few assumptions as possible). A mediocre API is one that does one of these well (either insanely simple but only if you're trying to do really basic stuff, or insanely powerful, but with a really steep learning curve, etc). A horrible API is one that does neither of these well.
There are several other good answers on this already, so I thought I'd just throw in some links I didn't see mentioned.
Articles
"A Little Manual Of API Design" by Jasmin Blanchette of Trolltech
"Defining QT-Style C++ APIs" also Trolltech
Books:
"Effective Java" by Joshua Bloch
"The Practice Of Programming" by Kernighan and Pike
I think a good API should allow custom IO and memory management hooks if it's applicable.
A typical example is you have your custom compressed archive format for data on disk and a third party library with a poor api wants to access data on disk and expects a path to a file where it can load its data.
This link has some good points:
http://gamearchitect.net/2008/09/19/good-middleware/
If the API produces an error message, ensure that the message and diagnostics help a developer work out what the problem is.
My expectation is that the caller of an API passes in input that is correct. A developer is the consumer of any error messages produced by the API (not the end user), and messages aimed at the developer help the developer debug their calling program.
An API is bad when it is badly documented.
An API is good when it is well documented and follows a coding standard.
Now these are two, very simple and also very hard points to follow, this brings one into the area of software architecture. You need a good architect that structures the system and helps the framework follow its own guidlines.
Commenting code, writing an well explained manual for the API is Mandatory.
An API can be good if it has a good documentation which explains how to use it. But if the code is clean, good and follows a standard inside itself, it doesnt matter if it doenst have a decent documentation.
I've written a little about coding structure here
I think what is paramount is readability, by which I mean the quality that makes the greatest number of programmers to make sense of what the code is doing in the shortest possible amount of time. But judging which piece of software is readable and which is not has that indescribable human quality: fuzziness. The points you mention do partly succeed in crystallizing it. However, in its entirety it has to remain a case-by-case affair and it would be really hard to come up with universal rules.
Our application is interfacing with a lot of web services these days. We have our own package that someone wrote a few years back using UTL_HTTP and it generally works, but needs some hard-coding of the SOAP envelope to work with certain systems. I would like to make it more generic, but lack experience to know how many scenarios I would have to deal with. The variations are in what namespaces need to be declared and the format of the elements. We have to handle both simple calls with a few parameters and those that pass a large amount of data in an encoded string.
I know that 10g has UTL_DBWS, but there are not a huge number of use-cases on-line. Is it stable and flexible enough for general use? Documentation
I have used UTL_HTTP which is simple and works. If you face a challenge with your own package, you can probably find a solution in one of the many wrapper packages around UTL_HTTP on the net (Google "consuming web services from pl/sql", leading you to e.g.
http://www.oracle-base.com/articles/9i/ConsumingWebServices9i.php)
The reason nobody is using UTL_DBWS is that it is not functional in a default installed database. You need to load a ton of Java classes into the database, but the standard instructions seem to be defective - the process spews Java errors right and left and ultimately fails. It seems very few people have been willing to take the time to track down the package dependencies in order to make this approach work.
I had this challenge and found and installed the 'SOAP API' package that Sten suggests on Oracle-Base. It provides some good envelope-creation functionality on top of UTL_HTTP.
However there were some limitations that pertain to your question. SOAP_API assumes all requests are simple XML- i.e. only one layer tag hierarchy.
I extended the SOAP_API package to allow the client code to arbitrarily insert an extra tag. So you can insert a sub-level such as , continue to build the request, and remember to insert a closing tag.
The namespace issue was a bear for the project- different levels of XML had different namespaces.
A nice debugging tool that I used is TCP Trace from Pocket Soap.
www.pocketsoap.com/tcptrace/
You set it up like a proxy and watch the HTTP request and response objects between client and server code.
Having said all that, we really like having a SOAP client in the database- we have full access to all data and existing PLSQL code, can easily loop through cursors and call the external app via SOAP when needed. It was a lot quicker and easier than deploying a middle tier with lots of custom Java or .NET code. Good luck and let me know if you'd like to see my enhanced SOAP API code.
We have also used UTL_HTTP in a manner similar to what you have described. I don't have any direct experience with UTL_DBWS, so I hope you can follow up with any information/experience you can gather.
#kogus, no it's a quite good design for many applications. PL/SQL is a full-fledged programming language that has been used for many big applications.
Check out this older post. I have to agree with that post's #1 answer; it's hard to imagine a scenario where this could be a good design.
Can't you write a service, or standalone application, which would talk to a table in your database? Then you could implement whatever you want as a trigger on that table.