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
Related
Alright. I know this may draw some heat as "not good question"/etc., but I haven't found anywhere describing the process in particular (all the resources I've found describe the client-side requesting, not the server-side responses).
I'm going to be working on writing an iOS app in the next coming months necessitating the use of a web server. There are many resources on how to set these up, get them a static IP, etc. but I haven't found any clear ones (and by clear, I mean intelligible by someone not already experienced in it) on how to write a program for such a server that actually responds to the HTTP or client request.
Suppose I have a dummy app and web server combo where the app posts an HTTP request for the time. How would I write an app for the server to bounce the time back when the request comes in? Ideally, I'd like to write this in Objective-C as it's the language I've had the most experience in (whether forced or by choice).
Again, I apologize if it isn't a good question or very clear - I just haven't found any resources that are able to give me much of a place to start.
Your question could probably be described as 'too broad', but I will give it a shot anyway. Disclaimer: I haven't written much server-side code but I have been programming in objc for years now.
The reason you haven't found (m)any resources to help you do what you want to do is because Objective-C is rarely used for writing server-side code. Exactly why that is the case is no doubt a long story, but essentially the answer is because many of the dominant technologies out there (PHP, Python, C#, Java, to name only the prevailing languages) have feaures and associated frameworks that are better suited for that purpose.
In other words, although I can doubltless be done, you are probably better off using something other than Objective-C for the task because:
You will have many more resources available to help you get your job done.
You will have a much larger community that you can query for assistance when (not if) you encounter an obstacle.
You will not have to do many things the hard way because there will be existing tools to make it easier.
I would also recommend you to use PHP as the server-side programming language.
Some mounths ago I was in the same situation as you. We have planned to write a app (Android) which loads some data from a webserver. I've never programmed server-side code till the beginning of the project. So it was quiet interessting and new for me.
We have choosen PHP as the server-side language.
All I can say is, that it was really easy to learn and write your first scripts to get a response to a HTTP-Request. Also the usage of MySQL as the database is really easy and it works fine with PHP.
PHP is a standard. You can find a huge amount of documentation and examples. And of course tutorials and good books ... ;)
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 am currently developing a very simple web service and thought I could write an API for that so when I decide to expand it on new platforms I would only have to code the parser application. That said, the API isn't meant for other developers but me, but I won't restrict access to it so anyone can build on that.
Then I thought I could even run the website itself through this API for various reasons like lower bandwidth consumption (HTML generated in browser) and client-side caching. Being AJAX heavy seemed like an even bigger reason to.
The layout looks like this:
Server (database, programming logic)
|
API (handles user reads/writes)
|
Client application (the website, browser extensions, desktop app, mobile apps)
|
Client cache (further reduces server reads)
After the introduction here are my questions:
Is this good use of API
Is it a good idea to run the whole website through the API
What choices for safe authentication do I have, using the API (and for some reason I prefer not to use HTTPS)
EDIT
Additional questions:
Any alternative approaches I haven't considered
What are some potential issues I haven't accounted for that may arise using this approach
First things first.
Asking if a design (or in fact anything) is "good" depends on how you define "goodness". Typical criteria are performance, maintainability, scalability, testability, reusability etc. It would help if you could add some of that context.
Having said that...
Is this good use of API
It's usually a good idea to separate out your business logic from your presentation logic and your data persistence logic. Your design does that, and therefore I'd be happy to call it "good". You might look at a formal design pattern to do this - Model View Controller is probably the current default, esp. for web applications.
Is it a good idea to run the whole website through the API
Well, that depends on the application. It's totally possible to write an application entirely in Javascript/Ajax, but there are browser compatibility issues (esp. for older browsers), and you have to build support for things users commonly expect from web applications, like deep links and search engine friendliness. If you have a well-factored API, you can do some of the page generation on the server, if that makes it easier.
What choices for safe authentication do I have, using the API (and for some reason I prefer not to use HTTPS)
Tricky one - with this kind of app, you have to distinguish between authenticating the user, and authenticating the application. For the former, OpenID or OAuth are probably the dominant solutions; for the latter, have a look at how Google requires you to sign up to use their Maps API.
In most web applications, HTTPS is not used for authentication (proving the current user is who they say they are), but for encryption. The two are related, but by no means equivalent...
Any alternative approaches I haven't considered
Maybe this fits more under question 5 - but in my experience, API design is a rather esoteric skill - it's hard for an API designer to be able to predict exactly what the client of the API is going to need. I would seriously consider writing the application without an API for your first client platform, and factor out the API later - that way, you build only what you need in the first release.
What are some potential issues I haven't accounted for that may arise using this approach
Versioning is a big deal with APIs - once you've created an interface, you can almost never change it, especially with multiple clients that you don't control. I'd build versioning in as a first class concept - with RESTful APIs, you can do this as part of the URL.
Is this good use of API
Depends on what you will do with that application.
Is it a good idea to run the whole website through the API
no, so your site will be accessible only through your application. this way This implementation prevents compatibility with other browsers
What choices for safe authentication do I have, using the API (and for some reason I prefer not to use HTTPS)
You can use omniauth
Any alternative approaches I haven't considered
create both frontends, one in your application and other in common browsers
What are some potential issues I haven't accounted for that may arise using this approach
I don't now your idea, but I can't see major danger.
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 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).