How are people managing multiple API versions with API Blueprint?
It doesn't seem that the format supports version sections within a single file, so I'm left thinking that multiple files with indicators in the filename are the best option.
We want to leverage the tools to create a central mock-server and doc commons, and will need to handle evolving multiple versions of each API.
Managing multiple versions via branches seems inconvenient for us, so we render the entire document with multiple versions of APIs in one page. Our users need to be able to read both versions by just prepending v1 or v2 in front of the URL. So, we have a node app that handles the documentation requests and renders the doc via aglio node module.
The following is how we organize the docs.
Users can request /docs/en/spec.
The en part determines the language of the document as we support different languages.
Because the entire document is pretty huge we split it into files based on the Blueprint Group (the thing that starts with # Group GroupName)
When a request comes in, we first look if we have previously compiled the doc and have a cached version, so we don't recompile every time (it's pretty intensive work especially when the doc is large).
If we have no cached version, we read all *.md files in the docs/en directory.
Sort the filenames alphabetically, concat their contents, and pass to aglio which produces a nice html content. We cache this content into a file and later pipe it to the client on each request.
The UI provides the table of contents (side menu on the left) which has, for instance, the following format.
Auth
Projects
Project Users
...
Groups
Groups v2
Now each Group of APIs has a distinct URL which is prepended with /v1 by default. When we introduce a new version of a specific API, we create a new # Group Groups v2 which is prepended with /v2. This way our users can see and choose multiple versions of the APIs in one page.
The nice things about the aglio node module is that it provide multiple themes for the UI which provides a nice navigation so that our users don't feel the page is too overloaded. Among the themes you can choose either single-page UI or multi-page UI where on selection of the API the page with the corresponding API is loaded and the URL is changed.
Implementing this logic is very simple. Hope this helps.
There is another idea which we are considering right now but haven't started just yet. It is to avoid splitting APIs into different # Groups and instead modify the Jade template used by aglio and make sure it supports multiple versions out of the box.
It might be best to version the blueprint file in a versioning repository and treat different branches as different API versions. You can even have the blueprint in the same repo/branch as the API server implementation.
If you're versioning using GitHub, Apiary can connect to GitHub and you can setup different branches to be picked up by different documentations in Apiary.
Related
I have been working my way into Magento2 for quite some time. From time to time I find new URLs by accident - mostly when I Google for a function or feature.
So that I don't forget to style anything in a new store or also to test functions I would like to have an overview of all automatically created pages which can't be maintained in the backend.
As examples these URLs would be here:
/sales/guest/form
/contact
...
Should the whole be version dependent gladly from 2.4.0 and upwards
I am trying to write an XD plugin that dynamically populates an artboard with components, but I don't see any mention of components in the XD plugin API. Is it possible to look through the file and find available components and place them on stage? Better yet, maybe even pull a component from a specific file in the cloud?
Unfortunately, it isn't possible to create symbol instances (that's what components are called in the APIs), yet. Here is the explaining quote from the plugin docs:
It is not currently possible for plugins to create a new component definition or a new SymbolInstance node, aside from using commands.duplicate to clone existing SymbolInstances.
(https://adobexdplatform.com/plugin-docs/reference/scenegraph.html#symbolinstance)
There is a feature request open for it in the official plugin developer forums which you can vote for. According to Steve Kwak (Adobe), however, this seems to be problematic due to the edit context, meaning it may still take a while until we get API access to that.
There, unfortunately, also, as of yet, isn't any way to list the available symbols for a document. For the other asset types, this is possible via the assets module (cf. https://adobexdplatform.com/plugin-docs/reference/assets.html), but not (yet) for symbols.
I hope this helps (although it's probably not the answer you've hoped for).
I want to generate the whole action JSONs in code, and then upload them, instead of working through the console.
There is an option to download the whole package as a zipped JSON and theoretically you can also upload. That might supply a hint on how to create the JSONs.
However, these files have all kinds of IDs for the different building blocks, such as Intents or Entity. So, when I export from DialogFlow, of course I get IDs for these.
But, if I want to create a new google action, do I generate these action IDs myself?
Is there documentation on what the structure of these JSONs should be?
The format used by the export/import process is not documented, and while you can try to work with it, there is no guarantee that it will continue to work in the future.
Depending on your needs, it may be better to work with the Dialogflow API (the former API of API.ai). This provides an API to build and modify Intents and Entities (and do some other things). It isn't clear, however, that this provides access to the settings for various integrations.
I'm developing a small data-crunching / visualization app in Sinatra, and am split between two options.
The functionality is that you:
Upload a file to the app.
See a nice visualization of its contents.
Maybe start over with a new file.
So my choices are:
Letting both views (upload and results) be managed by the same template, thus creating a single-page app.
Splitting uploads and the visualization between two pages. You upload a file to '/', then are redirected to that file's URL which displays the results.
Which one is better? The advantage of the first is that I can manage it all within the same page, by passing some local vars between the two views.
On the other hand, the second seems like the more RESTful option - because each uploaded file gets its own URL and can be treated as a resource (more fine-grained control).
So, if you want to provide a RESTful API as well along with the web application, it is good idea to have tow different routes.
If you are planning to have just a web UI, it depends on how much control you want to give to the end-user.
Nothing is wrong with either of the approach. It depends on how much ease you can provide.
DocPad is described as being comparable to other static site generators, but it is also described as being "not limited to static site generation".
I've been browsing the DocPad website and other documentation and haven't yet been able to find anything that seems to explain how to incorporate dynamic content, and what types of limitations may be involved?
As a relative beginner, I am wondering if anyone can help me better understand the methodology whereby dynamic content would be incorporated into DocPad...? e.g. AJAX, and dynamic server-side scripts for doing things like dynamically loading pictures from Flickr into a webpage when a certain tag is clicked...
Thanks.
So there's a few ways DocPad facilitates dynamic content:
Via the regenerateEvery configuration option. This will regenerate your website every so often you specify. This great when combined with plugins like feedr for pulling in data from remote feed sources (like your latest social activity), as well as repocloner which clones out and keeps a git repository up to date inside your project. The benefit of this option is it's really easy to do and provides the illusion of a dynamic website. For instance the Benjamin Lupton Website applies this method to keep it's statistics on the home page, as well as the social data in the sidebar up to date. Every hour it regenerates with the latest information. Making it fast, and also illusively dynamic.
Via the dynamic meta-data property. When set to to true this tells the DocPad server we should re-render that document on each request, rather than just once. This works great inside the Kitchensink Skeleton for search pages and misc forms. This way is most similar to PHP development.
Via the serverExtend event. This event allows you to hook into and extend the DocPad server, allowing you to add extra server-side logic, handling, etc. Common use cases is to add extra routing to your server to handle route aliases, adding form processing such as a contact form, or to add a RESTULful interface for a Backbone.js application. The DocPad Website uses this to add extra routing and a regenerate post-receive hook for the documentation. The NodeChat Skeleton uses this to add the Socket.io server-side logic.
Via the API. This way is the most involved but can be quite rewarding if you just wish for DocPad to be a small part of an existing node.js application. With this, you can create a DocPad instance in your code and interact with it. The grunt-docs grunt task utilises this :)