Which one makes process easier, minimum lines to code and easy to use.
The Java SDK will be easier, assuming you are used to coding in Java. With using the REST API directly, you have to managing the signing logic yourself, as well as be familiar with HTTP semantics like URI, path, query params, headers, body, etc. The Java SDK (and the other OCI SDKs) abstract that all away for you.
In the AWS SDK, EC2 instances can be launched programmatically via the AmazonEC2Client. Does GCP in general or Compute Engine specifically just offer the CLI-based gcloud command for the equivalent operation? Or can GCE instances be controlled from Java/Python/Go/etc as well? Which SDK exists for those languages and where are the examples & docs for this?
I am looking for the equivalent of this in the GCP world:
client = new AmazonEC2Client(credentials);
client.runInstances(new RunInstancesRequest())
You're looking for the Google Cloud Client Libraries, of which gcloud-java is the Java implementation. There are also Client Libraries in Go, Node.js, Python, and Ruby.
Under the covers everything in Google Cloud is available via an API, so even if there isn't a client library for what you're trying to accomplish, it can be done programmatically by calling the API directly.
The documentation on launching instances has an API tab that shows both Client Library and REST API examples.
Looks like this is still in alpha but it is available on Github: here and here. There is an example for starting GCE instances in the java-docs-samples project.
I've been looking at asp.net Web Api, and I like the simplicity of implementing a practical web service.
However, how can I document/specify the interface of a service implemented like that? For example, is there any spec I can pass on or generate to a Java guy with no .NET background that will let him easily call and consume the service? What can I give to the javascript guy?
Ideally, I'd like the benefits of SOAP/XSD or something like it (easy to deserialize with nicely typed objects) for the java guy, while retaining a service that's callable from a web browser too (i.e. supports non-crufy JSON).
Update
It's worth noting that since I originally posted this question, I discovered ServiceStack which deals with this more naturally; supporting JSON, SOAP, and WSDL out of the box for the same service, as the client chooses. If you really want SOAP+JSON, it may be a better framework than ASP.NET Web Api.
Update March 2016
It has been a while since this was answered and the tooling for documenting any Rest API has come along a lot. We are currently evaluating Swagger 2.0 now spawning out to the the Open Api Initiative, RAML and API Blueprint.
For WebAPI projects there is a tool Swashbuckle that auto creates Swagger (Open API) format documentation.
Format for documenting a REST service:
There are some attempts at structuring and standardising the description of REST services:
Web Application Desciption Language (WADL)
Web Service Description Language 2.0 (WSDL 2.0)
I think it is fair to say neither of the two approaches above have very wide adoption, but WADL does look like a nice concise format - a quick XSLT over the top and it could be a nice human readable format. There lots of examples of WADL for some famous API's at the apigee github site here.
When trying to find a documentation format that is appropriate I tend to look for "inspiration" from others.... Apigee do a lot of research in this area and have this as documentation for one of their API's here or take a look at Facebook's social graph api here.
The examples are largely in line with the advise here
How to auto document:
Using .NET: There is a good example of auto generating a WebApi "help" page here. A logical extension of this example may be to get it outing a WADL formated version as well...
Using Java: Jersey is a tool used in the Java community to generate WADL automatically.
What to share with the other developers:
Your Javascript guy will most likely want a manual like the Facebook and apigee one; giving the dev examples of the resources, urls, response codes etc. The most important thing here will be supporting JSON as the primary content type this will be the easiest for him/her to consume and work with by far.
Your Java guy would also want the manual, but also in theory they could be given example XSD for any XML representations of the resources you send/consume (assuming they make the request as "Content-Type: appplication/xml"). This may help them build proxy classes etc. JSON to Java and .NET converters are available online and given the example resources in your manual they should simply be able to use one of these types of services to quickly create proxies. Generate Java class from JSON?.
If you absolutely must have auto discovery, auto proxy generation etc then you may need to offer a choice of both REST and SOAP (with WSDL) endpoints - relevant question here: ReST Proxy Object Generator.
You can use IApiExplorer interface and ApiExplorer class in order to create a help page for your Web Api service. This help page will describe the REST methods exposed by your service so any developer who understands how REST works will be able to use it (regardless the language). Please read below links for details and samples:
ASP.NET Web API: Introducing IApiExplorer/ApiExplorer
ASP.NET Web API: Generating a Web API help page using ApiExplorer
Documenting your ASP.Net Web API’s
Does anyone know of any project to expose the DRMAA API (job scheduling and maintenance API) from SGE (Sun Grid Engine) as a web service API? A RESTful API would be best.
I do not think there are any web service API for SGE. I found drmaa-python pretty easy implementing in python script that can be called from server side scripts like PHP.
There is nothing like this available at the moment, but:
The Open Grid Forum started a new standardization activity to define how DRMAAv2 can be exposed as RESTful API. The specification draft is publicly available.
Since more and more people ask for such a remote interface, implementations might be available pretty soon. They are most likely to be announced by the OGF OCCI working group, so follow them if you are still interested.
Mapping such an implementation to the DRMAAv1 library in GridEngine should be relatively straightforward.
What is the accepted definition of an API compared to the definition of an SDK? Both seem to be used interchangeably, so I'd imagine that some libraries dubbed APIs are in reality SDKs, and vice versa. Also, is there a reason for this distinction?
Thanks!
An API, or application programming interface, defines a set of classes, functions, and structures to be used by an application to make use of some library or subsystem. For example, both the windows multimedia subsystem, and windows sockets subsystem both have their own API. An API is not a concrete entity, you can't point at a file and say that the file itself is an API. An API is merely a specification for a communications protocol that a program needs to use to make use of a library or subsystem.
An SDK, or software development kit, contains tools, documentation, and needed files, to program against 1 or more APIs. Some SDKs, but by no means all, may contain sample code to demonstrate how an API can be used. 2 examples of an SDK are the Windows Platform SDK and the .NET Framework SDK.
The most likely reason the terms are used interchangeably is because sometimes an SDK only has the tools, documentation, and files for a single API, and both the API and SDK share the same name. An example of this would be the SDK for developing winamp plugins.
API - Application Programming Interface. This is what you write code to.
SDK - Software Development Kit. These are the libraries that you need so you can code. An SDK likely has many different api's contained in it.
None of the answers I've seen so far really capture it clearly and completely.
The two terms are not interchangeable and if someone uses them interchangeably, it indicates a lack of understanding or preciseness.
API - Application Programming Interface. Exposed by a class library. Utilized by an application. When you build an application that uses the library, this is the interface your code uses to connect to or call into the library. In other words the set of rules and conventions applications must follow to use the library. The API includes the classes, their methods, the parameter lists for the methods, and other supporting elements (like enumerations, constants and so on). An API is an abstract artifact: You cannot download an API, or install an API. You can describe an API, and you can use one. The library itself is the concrete realization of the API, the delivery mechanism.
SDK - Software Development Kit. This is a concrete thing. You can download an SDK, install it, store it. An SDK includes:
libraries, which, as you know, expose or provide APIs.
header files (if applicable)
documentation - readme files, help files, release notes, reference documentation, programming guides. Realized as .CHM files, pdf documents, etc.
tools - such as compilers, assemblers, linkers, profilers, debuggers, optmizers, test tools, and more.
sample code and sample apps - showing how to use the API
maybe some other stuff that doesn't fit into one of the above categories
A Concrete Example:
the Java SDK is a downloadable, versioned thing. It delivers libraries, tools (on windows: javac.exe, java.exe, jar.exe, etc), all the help files and API doc, and source code for the libraries.
the API for Java is the set of rules your code must follow to invoke the libraries; these rules are described in the API documentation.
An API is an Application Programming Interface -- its something your program can talk to. An SDK usually includes an API along with documentation for the API. An API is not required to contain documentation. An SDK may include the API Components, but will always include the documentation.
APIs can exist within SDKs but not vice versa. SDKs generally contain a complete specifiction of a framework or environment. For example the Java SDK contains a full specification of the Java language plus tools, external libraries and whatever else the vendor decides to throw in there. The java apis are simply the interface to those specifications.