Medium’s New API

October 8th, 2015

Yesterday, Medium CEO Ev Williams announced a number of new features for the publishing service, but the one that interests me the most is of course the debut of a new publishing API. The “API” for any publishing service is a sort of interface for 3rd party apps that allows the content of a blog to be read, amended and edited outside of the service’s own web interface. Without an API, a desktop editor like MarsEdit cannot connect to and edit a blog’s posts.

Support for APIs used to be very strong not only for blog publishing services, but for photo sites like Flickr, and micro-blogging sites like Twitter. That enthusiasm seems to have waned in recent years. Popular publishing services such as WordPress, Blogger, and Tumblr still support relatively robust APIs, while Squarespace completely abandoned their API, and Medium has kept us on pins and needles, until now, as to whether they would ever support one.

The new API, which is well-documented on GitHub, seems off to a good start. It’s a REST based design that shares some design similarities with Tumblr’s and Blogger’s APIs. There are also some interesting decisions that set the API apart from any others I’ve seen. Here I present my impressions based on a short tour of the API documentation, and a bit of tinkering with it at the command line.


The API supports authentication by way of the relatively standard OAuth2 web-based scheme, through which users are able to authorize a client without ever providing their password. In addition, it supports a “self-issued token” solution through which a user can obtain a token on that a client app or service can then use to directly access their Medium content. Currently, Medium is limiting access to the full OAuth based system, so anybody who wants to play around with the API will need to do so using a self-issued token.

License & Attribution

One of the most unique aspects to Medium’s API is the provision for specifying a canonical URL and license on a post being submitted to the service. The canonical URL refers to another web location that should be considered the original, or most authoritative version of a post, while the license designates whether the post’s copyright terms stipulate a post is sharable as public domain or under a particular Creative Commons license. These attributes together indicate that Medium expects and encourages users of the API to contribute content that is not intended to be exclusive to Medium.

As a blogging enthusiast, I like the presence of these attributes because it implies support for a broad range of API client uses, and also because it acknowledges the value of diversity of web content. One of the criticisms of Medium over the past couple years has been the extent to which it encourages writers to abandon their own custom domain names in favor of a proprietary based soapbox. These attributes encourage writers who favor their own canonical web sites to nonetheless engage in Medium’s network of readers, writers, and commenters.


The extent to which the API supports working with posts boils down to a single mechanism for submitting a post to the service. It’s not possible to enumerate the list of existing drafts or published posts, e.g. to crosspost to another service or backup your posts to a local archive.

Because of the REST design for the API, there is a natural improvement that would solve this problem. Currently, Medium supports POST access to add a new entry to the collection of posts:

POST /v1/users/<userID>/posts

A typical REST based API for managing assets would also support GET access to this same URL, to facilitate reading the list of existing posts.


Unfortunately, the interface also does not support amending the contents of any post that has been published. So, for example, if you’ve discovered moments after publishing that you left a nagging typo, or got a link wrong (it happens all the time), the API offers no capacity to redo the submission, replacing the contents of the post with updated values. Again, REST conventions have the roadmap for this functionality pretty clearly outlined: while a POST request is typically used to add a new post to a collection, a PUT request to a specific post’s resource URL should be interpreted as updating its content.

Markdown Support-ish

A welcome feature for Markdown fans is the option through the API to specify that the post’s content should be interpreted as either HTML or Markdown formatted text. As far as I know, Markdown is not supported in Medium’s web-based interface, so this may be the debut of “official support” for Markdown on Medium.

Unfortunately, the Markdown support through the API seems to be a one-time conversion from Markdown to HTML, at the time of submission. This means users can write in Markdown for the initial composition of a post, but any further edits (through the web interface only, see above) will need to be done using Medium’s default rich WYSIWYG editor.

A more attractive long-term solution for Markdown fans would be to support storing Markdown text literally in Medium’s database, and converting it to HTML only for presentation on the web. This leaves the pristine Markdown available for perpetual edits either moments or years after the post is first published. This would require updating the web interface to support editing content as plain text, but would be a welcome change for anybody who favors editing in Markdown.

Image Uploads

The API exposes a mechanism for uploading images, but permission to use this aspect of the API will be granted by Medium on a case-by-case basis to applications that Medium deems suitable. This means that for self-issued tokens, image uploads are not possible.

Because I’m using a self-issued token for the time being, I wasn’t able to test this aspect of the API, but it looks relatively straightforward. I appreciate that they support a variety of image formats, including animated GIF, and even TIFF. I have to wonder if at least the TIFF files will be converted to PNG or something more web-friendly.

In response to an image upload, the API vends clients a URL and MD5 hash of the image so that a client could take care to reuse an existing resource rather than upload it again. This is a nice touch, but it would be aided by also supporting a mechanism for listing all the existing images on the blog. Again, using the conventions of a REST API for collection data, a GET against the images URL could do the trick to vend a paged list of existing resources.

In any case, the support for image uploads is very welcome, especially in comparison with Tumblr’s long-standing, nonsensical omission of a similar API mechanism for arbitrary image uploads.


The API has a funny caveat about the “title” attribute supplied for a post:

Note that this title is used for SEO and when rendering the post as a listing, but will not appear in the actual post—for that it must be specified in the content field as well.

This leaves client developers is an awkward position where they will need to muck around the user’s content in order to obtain the (likely) desired outcome that a post should show its own title. When I write a new post in Medium’s web-based editor, the title I type into the Title field is respected and sticks with the post as a bona fide title. Through the API however the title must be snuck into the content of the post. It would be better, in my opinion, if the API designated a more fail-safe mechanism for ensuring that a specific title is used as a visible title heading for a post.

A Good Start

My interest in the new Medium API is obviously based in my hope to support the service from MarsEdit. The current limitations, particularly with respect to listing or existing posts, would make it difficult to support Medium at the same level of functionality as other publishing systems. I’m encouraged by the progress though, and am hopeful that in response to feedback from myself and others, they will continue to develop the API into a truly first-class experience for a wide range of 3rd party solutions.

OS X El Capitan

September 29th, 2015

Tomorrow, Apple will release the latest version of OS X: 10.11 “El Capitan.”

All Red Sweater apps have been tested against the forthcoming release, and there are no known incompatibilities.

Please let us know if you run into any problems or have specific questions about our apps.

Cmd-Number Shortcuts For Safari 9

July 9th, 2015

If you’re a Safari user and you’ve updated to the Safari 9 or OS X 10.11 beta, you may have noticed a minor change in the default keyboard shortcuts for the app.

In Safari 8 and earlier, keyboard shortcuts combining the Command key and a number, e.g. Cmd-1, Cmd-2, Cmd-3, would open the corresponding bookmark bar item. So if you arranged your most-frequently-visited sites in the first few bookmark bar slots, you could easily jump to those pages by muscle memory thanks to these shortcuts.

In Safari 9, these shortcuts now switch to any open tabs you have in a Safari window. This will come as a surprise to folks who have gotten used to e.g. using Cmd-1 to quickly jump to e.g. Google News, or Yahoo Stocks.

The implicit shortcuts for bookmark bar items are still available, but you have to add the option key into the mix. So where you used to press Cmd-1, you must now press Cmd-Opt-1.

This may not be a big deal to you, and you may choose to simply adapt, but for those who got used to the old behavior and want to preserve a similar functionality, FastScripts can do the job of putting things back into order for you.

Safari’s scripting interface doesn’t support selecting a specific bookmark bar item by number, so FastScripts can’t exactly replicate the old behavior. What it can do though is bind (just about) any keystroke to a script that opens a specific URL in Safari. You might find after getting used to doing things “the FastScripts way” that you prefer it to the old Safari way, because you won’t be limited to using numeric shortcuts, and will instead be able to choose whatever shortcuts you like. For example, I use Ctrl-N as my shortcut to quickly jump to Google News.

Here’s a step-by-step procedure for adding shortcuts to Safari to open a specific URL:

  1. Download FastScripts. It’s free for up to 10 shortcuts.
  2. Launch FastScripts and find its icon in the upper-right corner of your Mac’s screen. It looks like this: MenuIconGray 2x
  3. Launch or activate Safari so it’s the front-most app.
  4. Click the FastScripts icon and select FastScripts -> Create Safari Scripts Folder.
  5. Download this script and copy it to the Safari scripts folder.
  6. Double-click the script to open in Script Editor.
  7. Change the URL in the script from “” to whatever URL you like, e.g. “”
  8. Save the script and rename it to e.g. “Open Google News”.
  9. Back in Safari, hold the Command down and select “Open Google News” from the FastScripts menu. This is a shortcut to quickly change a script’s keyboard shortcut.
  10. Set the desired keyboard shortcut in FastScripts’s preferences.
  11. There’s no step 11! From now on, whenever you’re in Safari and want to jump to that URL, just press the keyboard shortcut, and you’re done.

This sounds a bit more complicated to set up than it is in practice. Once you get the hang of it you’ll be able to quickly replace however many Cmd-Number shortcuts as you like in Safari, and it might even open the door to overriding behaviors of other apps. This is an area where FastScripts really shines. Enjoy!

MarsEdit 3.7.1: Finessing Apple Photos And Google Authentication

June 24th, 2015

MarsEdit 3.7.1 is available now on the MarsEdit home page, and will be submitted to the Mac App Store approval for approval by Apple.

This update addresses a couple issues that affect a minority of MarsEdit users. One fix is for Blogger users who ran into mysterious “JavaScript disabled” errors when trying to log in to their blogs. The other should eliminate a crash that could occur while loading the contents of an Apple Photos library in MarsEdit’s Media Manager.

  • Fix a crash that could occur while reloading Apple Photos Library
  • Fix a rare issue where users could encounter a “JavaScript disabled” error when trying to log in to Blogger

Let me know if you run into any trouble with the update!