Information for Developers to Make Their Apps Linkable (API Requirements for Compatibility with Hook)
This web page is for wise app-developers: those who would like their customers to be able to link the data of your app to anything they want.
Hook works with apps which have persistent documents, resources, or contexts which can be saved and opened or restored.
Hook works “out of the box” with many apps, using Hook’s default integration scripts. For other apps, we create “integration scripts” that communicate with the app.
Hook needs to be able to get the name of your app’s current resource, and a URL/ID for it. It needs to be able to open this resource using that URL/ID. We do not expect Hook to be able to get the name or URL/ID of an unsaved document.
Hook merely needs your app to provide an API to do the following.
Using your API, Hook or its enthusiastic automation community will create software integration scripts that enable users, via Hook, to link the data of your apps with your API.
We just need:
- An API to get the URL or ID of the current resource. This API could also return the name of the resource.
- An API to get the name of the current resource. This could be the overloaded into the previous API.
- A means of opening a resource, given a URL or ID
- A way of creating a new resource in your app, given a particular name — for apps that enable creation of items.
1. Getting the current item’s URL(s) or identifier
Hook needs a method to get the URL(s) (address(s)) or ID of the current item. Depending on your app, “current item” (aka, “current resource”) may mean different things, such as the currently open document or object; or the currently selected item (object or file) in a list.
- If your app transacts directly with files and the files can be accessed directly via the Finder Finder, then you should provide a method that returns the pathname, even if your app also has its own URL scheme.
- If your app provides its own URL scheme for items, then provide a method to get the URL of the currently open item.
- If your app has its own ID mechanism but not URL scheme, then at least provide a method that returns the ID of the current item. See opening items, below
The ID and URL must uniquely identify the resource, and it should be persistent. If the resource is renamed or moved, it shouldn’t affect the identifier or break the URL.
If the resources of your app have two different addresses (typically: a file path and a proprietary URL), then you can provide both addresses in a method that returns a complex return; or you may provide too different methods, one for each resource. The former is better in case there’s a delay between the method calls.
It is preferable for the API for getting the address(es) of the current item to also returns the name of the item, as described next.
1.1 Deep PDF linking
If yours is a PDF app, then it is very helpful to provide an API for getting the currently presented or selected page, and the top x and y coordinates of the selection (if any). The API should also specify the output parameter for the case where there is no selection. For instance, the x coordinate might be -1 in that case.
This information can be combined with the overall “get address” method. Or a separate API may be provided for it.
If your apps manage its own URLs, it is important to document your URL format such that apps like Hook can tell that two URLs refer to the same document, except that one URL has one set of in-file addresses, whereas the other refers to the same document but with different or no in-file parameters.
For examples of deep-linking of PDF APIs, see Deep PDF Links Take You Right Where You Need to Focus – Hook.
Douglas Englebart referred to this as “in-file addressability”.
1.2 Deep links in other apps
If your app represents data hierarchically, you may provide an API for other forms of deep linking. Ideally, for document-style apps, your URL scheme distinguishes the document from the address within the document (as web URLs typically do, with the
# symbol indicating a fragment). Please clearly document your URL scheme and API.
2. Getting the current’ item’s name
You should also provide a method to get the name of the current item, as defined above.
As mentioned above, it is preferable if this is one of potentially many results of the same method as is used to get the address of the item (e.g., returning a markdown link). But it can be its own method.
3. Opening the resource based on its address or ID
Obviously, it must be possible to open or restore the resource with the URL or identifier your app returned, per above. If your app already has an existing URL scheme and the URL can just be opened, then you don’t need to do anything more.
If your app uses IDs rather than URLs or pathnames, then you may simply provide a method or x-callback-url to open the item given the ID.
3.1 Opening deep links
If your app supports deep links, then please provide an API for accessing the page and x/y coordinates on that page. This could be a separate method to scroll to the particular page number and x/y parameters on that page, or it could be built-into the URL or method for opening the entire document.
4. Creating new items
If your application supports the creation of new items and those items are files exposed on the Finder, then CogSci Apps (and other developers) can automatically create new documents as long as we have a copy of a blank template and we know its filename extension(s). No API is required for such app.
If your application supports the creation of other types of items, then please provide an API for creating new items. The API should normally accept a name as an input parameter. It should return the name of the created item, following the addressing guidelines above,, and optionally the name of the item (in case your app has modified the name due to some of its rules).
By returning the address of the new item, it will be possible for users to enjoy the tremendous benefits of the
Hook to New function, where in one go Hook creates a new item and bidirectionally hooks it to a contextual item, while also bookmarking and potentially tagging both items.
You get extra points if your API also enables automation to:
- insert hypertext in the new item. Hook would then optionally insert a hyperlink back to the source directly into the new item (as it does for Apple Notes, Craft and Drafts, for example) or in the new item’s note field (e.g., as it does for OmniFocus).
- apply a tag to the new item (as Hook can optionally do with DEVONthink, Finder files and OmniFocus, for example).
Additional notes about URLs
If your software exposes the same data via a local app and via a web browser, it is important to ensure that third-party software can translate the URL received in the context of the app to the URL received in the context of a web browser. Using universal links may help.
It is important therefore for your web interface to expose in the address bar the URL of the current item. If the data is hierarchical, this should be reflected in the URL scheme or via an API, such that software can gauge the containment hierarchy. This will support deep-linking.
General API guidelines
Like any good API, your API should document any specific usage, parameter or condition restrictions. Please also document possible error conditions and their meaning. For instance , your “getAddress” API would have an error condition for the case where no item is currently open or selected. That information (error code) can then be passed on (translated) by Hook to the user.
For examples of how other apps have been integrated with Hook, and how Hook integration happens you can peruse the integration scripts in Hook itself. We recommend looking in particular at Hook’s integration with Craft , Drafts, OmniFocus and BBEdit.
We like showcasing great apps that integrate well with Hook, in our release notes, emails to customers, on our blog, on the Hook productivity forum, on social media and elsewhere.
Please don’t hesitate to contact us (email@example.com) if you have any questions. You can also ask questions directly on the Hook Productivity Forum to get our community talking about using your app with Hook.
What’s a Linkable App and Why Does Linkability Matter?
That question is addressed here.
We have mentioned AppleScript a lot in this document. However, an app can be linkable without supporting AppleScript. Hook can work with other APIs than AppleScript. For instance, the app might provide a command line interface for linking, which Hook could leverage. The key question is whether the app is truly linkable, which require automation for hyperlink described here.
By making your app linkable, you will be in the company of other great Linkable Mac Apps, and be better positioned to compete with them.
In this day and age. Consumers purchase many apps, and they need to be able to link their apps’ data to other apps. Otherwise, they will choose your competitor. And who can blame them?
- Supported/unsupported Apps
- Creating Integration Scripts
- Contacting Developers of Other Apps (This page)
- Example: Customizing Hook Integration with Things
- Example: Customizing Hook Integration with Xcode
- Example: Hook to New with Momenta’s Agenda app using x-callback-url