You might be familiar with Google Docs' (and presumably also the other 'office' apps) ability to communicate with a blog server to publish a post directly from its interface. (It's located in Share > Publish as a web page).
I'm interested in knowing the standard for the data transmission that this system uses. Of course, I can always reverse-engineer the code for one of the blog applications supported, but a formal specification would be more useful.
Thanks in advance!
It seems to support three types of API :
Blogger API
MovableType API
and MetawebBlog API
Those (at the the two last ones) seem to be based upon some kind of XML-RPC protocol (see also) ; so, the ability to use them has to be linked to what API (classes/methods) they export -- for blogging-software, those will be methods to get/create posts, most probably ; and only a few methods, I guess, so that using those API is not too complicated...
The first one seems to use some kind of ATOM-based format (see, for instance, what has to be used to create a new post)
Still, using that kind of "half-standard" API means you'll have to code some stuff each time you want your application to support a new API ; happily, there are not that many blogging-software related APIs : many blogging software tend to use the same ones, which is great : it allows you (or google docs, btw ;-) ) to publish to many different kind of software with only implementing the 2 or 3 most important / most used APIs.
For instance, the well-know platform Wordpress supports both Metaweb, Blogger, and MovableType APIs -- even if those were created for other software, at first -- coincidence (or not ^^ ) those are the same as Google Docs supports : the most used, I suppose ;-)
Actually, the Blogger API that Google Docs uses is the original (depricated) XML-RPC one, not the new GData API. The original Blogger protocol is the oldest and the simplest of the three supported (good for a quick implementation).
Related
We have our API versioning strategy based on URL.
I have couple of scenarios to add new enpoints , where I could not find any strategical reference for this.
Scenario 1:
An existing API having endpoints varyingly ranging from versions v1 to v4. Few endpoints are upto V2, few are upto V3, and few at v4.
In this situation If I have to add a new endpoint, Should I begin the version for the new endpoint at V4? Is there any standards for it.
Scenario 2
This is the different scenario. one of the API GW spanned across multiple microservices, and the micro services are grouped by resources within the gateway. so a resource have a one on one mapping against a service.
Similarly different API versioning exists btw resources here. Few resources were upto V3 and few are up to v5. if a new endpoint is required to be added to a resource which is already upto v3, should we add a new endpoint in v3 or should we create a v5 version of resource to add that specific endpoint?
Any suggestions would be helpful.
You're unlikely find a standard way of doing things. The closest thing to a standard is what Fielding and the HTTP specifications say themselves. You should expect these questions to enlist many subjective opinions. Here's my bias opinion based on experience and a deep understanding of the specifications...
Conceptually, there's no real problem with adding new endpoints to an existing API. Where this might be problematic is if your API is public and with public documentation. Once an API version is released, it should be immutable so that clients can rely on it. If you're adding surface area to your API, then I would recommend you create a new version. If you're unsure what that version will shape up to be in totality, you can always start with a pre-release version; for example, 4.0-preview.1.
Your second question seems to ask whether you should have symmetrical versions. You can, but it's solely at your discretion. You indicated that you have microservices, so unless you are building out an API for an entire product or suite, it is more flexible to allow an API to evolve independently. This will organically result in heterogenous API versions over time. That shouldn't be a problem IMHO. The key to making that manageable is to define a sound versioning policy, such as N-2 supported versions.
You've already elected to version by URL segment, so there's no going back. Versioning this way leads to a spider web of different URLs when the versions are not symmetrical. This is just one of the many problems you may encounter. Hypermedia is almost all but impossible to achieve when versioning by URL unless the versions are symmetrical. Ultimately, versioning by URL segment is not RESTful, despite being popular, because it violates the Uniform Interface constraint. The URL path is the resource identifier. v3/order/42 and v4/order/42 are not different resources, they are different representations. In the same way, I can ask for order/42 as application/json or application/xml, but they are not different API versions, even though they look completely different over the wire.
As an example, if you retrieve v2/order/42 and it has a link to customer/42, but the Customer API supports 2.0 and 3.0, how do you know which link to provide? If the client only knows how to talk v3/customer/42 and you give them v2/customer/42, it might break them. Furthermore, what happens if the Customer API doesn't support 2.0 at all? The Order API has to incorrectly assume v2 is a valid or it has to be coupled into knowing which versions are supported; both of which are not good. In all cases, the server still doesn't know what the client really wants. It is the client's responsibility to tell the server what it wants. Every other method of versioning does not have this problem as the URLs are always consistent. Let's say you version by query string with api-version, another popular choice. If you provide a link to customer/42, the link is valid regardless of API version. It's the client's job to know and append ?api-version=<value> to indicate to the server how they want to query the resource. This is why Fielding says that media type negotiation is the only way to version an API. It's hard to argue with the G.O.A.T., but using the query string or another header doesn't explicitly violate any constraints, even if media type negotiation would be better.
We have a medium size app (100+ SQL tables), and we often need to integrate it with partner APIs (with our system as a client/consumer). Process of designing such integration is non-trivial:
We often need to map columns in our database to fields in requests to partner API.
Some fields in requests to partner API must be constant, or conditional
In rare occasions output from one API response becomes an input to another API request
There are many resources on the web to document REST APIs - there are specific formats for that (Swagger, RAML, etc.). These formats allow efficient generation of client code and human-readable documentation. However these formats are not very helpful for describing how your app integrates with an API. We create lengthy Microsoft Word documents which contain more or less a copy of partner API methods with comments how every individual field should be used. Such solution seems sub-optimal.
Googling for better options did not yield many results, namely Swaggerhub seems to have "comments" functionality which seems to target the problem above and pretty much that's all.
Question: are there some tools, formats, workflows, ideas, etc. which facilitate designing and documenting API integrations described above?
I dont know which language you use, but i work with ApiDoc
https://apidocjs.com/
He is perfect to generate an API REST doc with comment in NodeJS, he can be used with many language
So, I stepped once at this problem. I had offered a website that used the SoundCloud API. Everything worked properly. Content was extracted from the JSON and placed in the layout of the website. However, I received an email one day from the owner of the website, which indicated that the website did not work properly. I then came out to investigate and came to the conclusion that the "problem" was not on my side, but at SoundCloud's side. I studied on the API page of SoundCloud and came to the conclusion that the API had received a major update, making the link with SC and the site no longer worked.
Lately I'm trying many new APIs to, including those from Instagram and Dribbble. I was therefore wondering if it is at all possible to ensure that such problems can be reduced in the future or it might be appropriate API pages of this third-party APIs to monitor?
There's no "right" answer. After many years of using and maintaining many APIs here are some of the conclusions I've come to:
The best providers let you work with a specific version of their API whose interface and expected behavior never changes. They might release bug fixes and new endpoints, but you can be confident that as long as the API is supported it will not break your system.
A good provider will provide an end-of-life date for each version of their API. It's up to you to keep track of when you need to update.
Paid services will often be supported longer than free services. Plus the contract / SLA will guarantee it remains available for a specific amount of time.
The most popular APIs often have mailing lists and/or blogs. For those that offer it, sign up to be notified of updates. For those that don't you'll have to monitor their blogs or news posts. And I suggest not using any service that would drop support for an API version without warning.
The documentation for Google Documents List API, seems to say that you can create a local document and upload it. Is there no way to actually create and edit a document on Google Docs through an API?
While the docs call it "uploading", everything boils down to sending an appropriately formatted HTTP POST request, so of course it can actually be a new creation rather than an actual "upload" of an otherwise existing file. (Creation through POST requests is similar to what's normally described as a REST API, though in real REST you'd typically use a PUT request instead of course).
You just need to create a blob of data representing your document in any of the formats listed here -- depending on your programming language, simplest may be text/csv for a spreadsheet and application/rtf for a text-document -- then put in in an appropriately formatted POST data. For example, to make a spreadsheet in the simplest way (no metadata), you could POST something like:
POST /feeds/default/private/full HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>
Content-Length: 81047
Content-Type: text/csv
Slug: Example Spreadsheet
ColumnA, ColumnB
23, 45
Each specific programming language for which a dedicated API is supplied may offer help with this not-so-hard task; for example, in Python, per the docs, the API recommends using ETags to avoid overwriting changes when multiple clients are simultaneously "uploading" (i.e., creating or updating docs). But preparing the POST directly is always possible, since the almost-REST API is documented as the protocol underlying all language-specific APIs.
Alex's answer, while undoubtedly correct, begs the question: "how do I do that via the Google Docs API?"
Here's a way (in Python, 'cause I'm that kind of guy):
import gdata.docs.service
import StringIO
client = gdata.docs.service.DocsService()
client.ClientLogin(username, password,
source='Spreadsheet Creation Example')
content = 'COL_A, COL_B, COL_C, COL_D\ndata1, data2, data3, data4'
ms = gdata.MediaSource(file_handle=StringIO.StringIO(content),
content_type='text/csv',
content_length=len(content))
entry = client.Upload(ms, 'Test Spreadsheet')
This is a small mashup of techniques that I found in http://code.google.com/p/gdata-python-client/source/browse/tests/gdata_tests/docs/service_test.py , which I in turn found via this post from the Google Group for the GData Docs API.
The key insights (for me anyway) were:
realizing that the MediaSource constructor's formal parameter "file_handle" will take any file-like object, and
discovering (as the OP's followup to the Google Group post mentions) that the unit tests are a great source of examples
(I wasn't able to find the Python-specific developer's guide referenced by Alex's doc link -- possibly it's been lost or buried in Google's move of documentation assets from code.google.com to developers.google.com. Alex's link now redirects to the more generic document that shows mostly .NET and Java examples, but only a little Python.)
As of Feb 4, 2019, Google Docs now has a REST API.
See documentation:
https://developers.google.com/docs/api/
(Sep 2019) There are 3 ways to create a document in Google Docs programmatically:
Google Docs REST API (low-level; Python, JS/Node.js, Java, C#/.NET, PHP, Ruby, Go, etc.)
Google Apps Script (high-level; JavaScript-only)
Google Drive API (low-level like Docs API above; both alternatives above can create or edit documents, but this one is create- or delete-only plus editing sharing/permissions)
The Docs API was officially launched in Feb 2019. I produced a high-level video overview of what a mail merge application using the API would look like. (It's not a full-fledged G Suite Dev Show episode but does link to a working sample.) Check out the various guides on using the API, including Quickstart examples in a variety of programming languages.
OTOH, Apps Script is a simpler, higher-level alternative. It's a custom server-side JavaScript runtime supporting apps that are hosted+executed in Google's cloud. Use objects to talk to various Google APIs (G Suite & beyond) without knowledge of HTTP, REST, nor OAuth2. You can also access external databases with its JDBC Service or call other apps via its URL Fetch Service.
With Apps Script, you can create standalone applications, document-bound applications (only works for a single document), or Google Docs Add-ons to extend the functionality of Google Docs. Here are the Google Docs Apps Script overview page as well as the Apps Script reference documentation for Google Docs (Document Service). I've also produced a variety of Apps Script videos if that's your preferred learning vehicle. If you're new to Apps Script, see my answer to a similar SO question for more learning resources.
Typically the Docs, Sheets, Slides, etc., APIs are used to perform document-oriented functionality while the Drive API is used primarily for file-based operations. However "create" is a special case where you can use either. See my answer to another SO question which shows the difference b/w creating a new Google Sheet via the Sheets API vs. the Drive API. (Both samples in Python.) Read this if you're interested in managing sharing or updating permissions of Google Docs.
What things should a developer designing and implementing an API for a community based website know before starting the heavy coding? There are a bunch of APIs out there like Twitter API, Facebook API, Flickr API, etc which are all good examples. But how would you build your own API?
What technologies would you use? I think it's a good idea to use REST-like interface so that the API is accessible from different platforms/clients/browsers/command line tools (like curl). Am I right? I know that all the principles of web development should be met like caching, availability, scalability, security, protection against potential DOS attacks, validation, etc. And when it comes to APIs some of the most important things are backward compatibility and documentation. Am I missing something?
On the other hand, thinking from user's point of view (I mean the developer who is going to use your API), what would you look for in an API? Good documentation? Lots of code samples?
This question was inspired by Joel Coehoorn's question "What should a developer know before building a public web site?".
This question is a community wiki, so I hope you will help me put in one place all the things that should be addressed when building an API for a community based website.
If you really want to define a REST api, then do the following:
forget all technology issues other than HTTP and media types.
Identify the major use cases where a client will interact with the API
Write client code that perform those "use cases" against a hypothetical HTTP server. The only information that client should start with is the response from a GET request to the root API url. The client should identify the media-type of the response from the HTTP content-type header and it should parse the response. That response should contain links to other resources that allow the client to perform all of the APIs required operations.
When creating a REST api it is easier to think of it as a "user interface" for a machine rather than exposing an object model or process model. Imagine the machine navigating the api programmatically by retrieving a response, following a link, processing the response and following the next link. The client should never construct a URL based on its knowledge of how the server organizes resources.
How those links are formatted and identified is critical. The most important decision you will make in defining a REST API is your choice of media types. You either need to find standard ways of representing that link information (think Atom, microformats, atom link-relations, Html5 link relations) or if you have specialized needs and you don't need really wide reach to many clients, then you could create your own media-types.
Document how those media types are structured and what links/link-relations they may contain. Specific information about media types is critical to the client. Having a server return Content-Type:application/xml is useless to a client if it wants to do anything more than parse the response. The client cannot know what is contained in a response of type application/xml. Some people do believe you can use XML schema to define this but there are several disadvantages to this and it violates the REST "self-descriptive message" constraint.
Remember that what the URL looks like has absolutely no bearing on how the client should operate. The only exception to this, is that a media type may specify the use of templated URIs and may define parameters of those templates. The structure of the URL will become significant when it comes to choosing a server side framework. The server controls the URL structure, the client should not care. However, do not let the server side framework dictate how the client interacts with the API and be very cautious about choosing a framework that requires you to change your API. HTTP should be the only constraint regarding the client/server interaction.