-
Notifications
You must be signed in to change notification settings - Fork 9
/
designsystem.apib
217 lines (139 loc) · 8.64 KB
/
designsystem.apib
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
FORMAT: 1A
HOST: https://api.thegrid.io/
# Design systems
The Design System is the piece of The Grid that builds a webpage from page content.
A set of design systems are provided by The Grid. These use techiques like
finite-domain constraint solvers, decision trees, content analysis,
and polyrythmic pagination in order to produce a page which:
* Is *content driven*, reflects the particular items on the page
* Is *visually pleasing*, respecting the users site preferences
* Is *effective* at achieving the purpose set by the user
In the future, we intent to support "plugins" which can hook into and extend existing design systems.
Such plugins could build sections for particular types of data, extend content analysis or heruristics,
add or modify rhythms (scoring functions).
In the meantime the *daring and ambitious* may implement an full design system
using the mechanism below.
# API
A design system is deployed as a `.js` file, and runs sandboxed in a browser using [JsJob](https://github.com/the-grid/jsjob).
On the server-side this is PhantomJS (with function.bind polyfill),
on client-side it runs in a WebWorker (no access to DOM).
The design system must expose a `polySolvePage` function as an entry point.
window.polySolvePage = function (page, options, callback) {
var html = "";
var err = null;
return callback(err, html, details);
};
The function will be called with a
[Page object](https://github.com/the-grid/apidocs/blob/master/schemata/page.yaml)
containing the data to be put on the page.
The `page` also includes the [Site config](https://github.com/the-grid/apidocs/blob/master/schemata/siteconfig.yaml)
for the particular page.
The `callback` should be called with the HTML page produced by the design system,
or an `Error` object in case of failure. `details` may be an object with design-system
specific information about the produced page or failure, for use in debugging and/or
machine learning.
Assets in the produced HTML page must either be inlined in the HTML (recommended for CSS, GSS),
or refer to a *stable* URL on a HTTPS enabled CDN (recommended for fonts, images).
<!-- TODO:
- describe article versus feed pages
- describe ordered versus non-ordered mode
- describe/show how to run a page build locally
-->
# Use custom design system
You can configure a site to use a custom design system,
by setting the `style` property to be a URL to .JS file implementing the API above.
`style: https://example.net/path/mydesignsystem-0.1.0.js`
It is heavily recommended that the JS is served over https. Also, we recommend
that the path is strictly versioned, each new code change gets a new URL, and
the configuration is updated to activate the new version.
Use `config` object of the `PUT /site/$id` API to change site configuration from an app.
For example, using the [configure-site example](https://github.com/the-grid/apidocs/tree/master/code-examples/coffeescript) to enable a
[trivial design system](https://developer.thegrid.io/designsystems/original-html.js).
thegrid-site-configure https://thegrid.ai/mysite style https://developer.thegrid.io/designsystems/original-html.js
Note: This will override the default design system completely!
To reset back to the default design system, remove the `style` key/value.
# Custom settings
If your design system has settings, they should be persisted in the site config.
You can use the API in order to build a web app with custom user interface to let users configuring settings.
For compatibility, it is recommended that all configuration keys are prefixed with your application/design-system name.
For instance, if you have an option for 'density', use something like `mysystem_density: 3.3` or use `mysystem: { density: 3.3 }`.
All changes to site configuration will trigger a rebuild of the pages on the site.
# Running locally
Assuming `mypage.json` is a page input datastructure, you can execute your designsystem locally using
thegrid-designsystem-run https://developer.thegrid.io/designsystems/original-html.js mypage.json > output.html
You can now open `output.html` in your browser.
You should have PhantomJS 2.x installed, and `phantomjs` should existing on PATH.
This is then executed in the same way as on the production infrastructure.
<!-- TODO:
- tool for getting page input datastructure
-->
# Tools
Designs systems are complex beasts.
In order to create them we have built a set of libraries, services and tools.
Several of these are already open source:
- [Grid Style Sheets](gridstylesheets.org) (GSS), constraint-based layout system
- [imgflo](http://imgflo.org), on-demand server-side image processing.
Helpers: [RIG](https://github.com/the-grid/rig) and [imgflo-url](https://github.com/the-grid/imgflo-url)
- [Grid Object Model](https://github.com/the-grid/gom) (GOM), HTML templating and transformations
- [finitedomain](https://github.com/the-grid/finitedomain), High-performance finite domain solver
- [Flowerflip](https://github.com/the-grid/Flowerflip), Promise-based finite-domain constraint solver
- [Regimen](https://github.com/the-grid/regimen), Chai.js-based expectations for item/block consumption
More to be released soon!
# HTTP APIs
# Group Registered design systems
A registered designsystem can be used across many sites by referring to it by name (istead of URL).
Such a designsystem can have many versions, and new versions will first be pushed into staging,
where pages are solved without influencing the live site. One can look at and analyze these page *solutions*,
and once one is confident of the quality of the new version, trigger rollout to all sites with
that designsystem.
If you want access to this functionality, you need an access token (secret) associated with your design system.
Contact [email protected] and mark the request with 'designsystem development', and include your TheGrid user UUID.
In the future, we may support self-service for registering new design systems.
These APIs are [Webhooks](https://en.wikipedia.org/wiki/Webhook) signed as [JSON Web Token](http://jwt.io/).
## Designsystem events [/designsystem_event]
For code examples, see
[thegrid-designsystem-update](https://github.com/the-grid/apidocs/blob/master/tools/designsystem-update.coffee)
and [thegrid-designsystem-collaborators](https://github.com/the-grid/apidocs/blob/master/tools/designsystem-collaborators.coffee)
### Registering new design system version [POST]
+ Request (application/json)
+ Response 202
### Setting design system collaborators [POST]
+ Request (application/json)
+ Response 202
# Group Solutions
A solution is the page output from a design system for a particular page-solving job, and associated metadata.
These APIs are authenticated with standard OAuth2 Bearer-token.
The application using them must request the `designsystem_review` scope.
Permissions are granted per-designsystem, to users registered as a collaborators of the designsystem in question.
## Designsystems [/designsystem]
### List available designsystems [GET]
Lists designsystems you are authorized to access.
+ Response 200 (application/json)
## Solutions [/designsystem/{system}/{?site,path,version,published,staged,limit,offset}/solutions]
Note that since we create multiple solution variants for one solve job,
and in future may ask user which one to publish, a solution can be `succeeded: true` but `published: false`.
And since user never sees or can publish staging results. `staged: true` implies `published: false`.
+ Parameters
+ site (optional, string) - Website to return results for. Ex: 'the-domains/d4'
+ path (optional, string) - Page path to return results for. Ex: "index.html" for frontpage.
+ version (optional, string) - Designsystem version to return results for. Ex: "0.10.0"
+ published (optional, boolean) - If true, return only solutions which were made live on a site.
+ staged (optional, boolean) - If true, return only solutions produced in staging. If false, only from production.
+ limit (optional, number) - Pagination limit. Defaults to 100
+ offset (optional, number) - Pagination offset
### List solutions [GET]
+ Response 200 (application/json)
## Solution details [/designsystem/{system}/solutions/{id}]
### Get details about a solution [GET]
+ Response 200 (application/json)
## Solution output HTML [/designsystem/{system}/solutions/{id}/output]
### Get solution output [GET]
Returns the HTML produced by design system for this solution.
+ Response 200 (text/html)
## Solution log [/designsystem/{system}/solutions/{id}/stdout]
### Get job stdout [GET]
+ Response 200 (text/plain)
## Solution error log [/designsystem/{system}/solutions/{id}/stderr]
### Get job stderr [GET]
+ Response 200 (text/plain)
<!-- TODO: allow retrieving solution details and screenshots -->