1openapi: "3.0.0"
2info:
3  description: ""
4  version: "2.1.0"
5  title: "Cayley API"
6  license:
7    name: "Apache 2.0"
8    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
9servers:
10- url: "http://{host}:{port}"
11  variables:
12    'host':
13      default: "localhost"
14    'port':
15      default: "64210"
16tags:
17- name: "data"
18  description: "Reading and writing data"
19- name: "queries"
20  description: "Querying the graph"
21paths:
22  /api/v2/formats:
23    get:
24      tags:
25      - "data"
26      summary: "Returns a list of supported data formats"
27      description: ""
28      operationId: "listFormats"
29      responses:
30        200:
31          description: "success"
32          content:
33            'application/json':
34              schema:
35                type: "object"
36                properties:
37                  id:
38                    description: "unique name of the format"
39                    type: "string"
40                  read:
41                    description: "format is supported for loading quads"
42                    type: "boolean"
43                  write:
44                    description: "format is supported for exporting quads"
45                    type: "boolean"
46                  nodes:
47                    description: "format can be used to describe nodes"
48                    type: "boolean"
49                  ext:
50                    description: "typical file extensions for this format"
51                    type: "array"
52                    items:
53                      type: "string"
54                  mime:
55                    description: "typical content types for this format"
56                    type: "array"
57                    items:
58                      type: "string"
59                  binary:
60                    description: "format uses binary encoding"
61                    type: "boolean"
62        default:
63          description: "Unexpected error"
64          content:
65            application/json:
66              schema:
67                $ref: '#/components/schemas/Error'
68  /api/v2/read:
69    get:
70      tags:
71      - "data"
72      summary: "Reads all quads from the database"
73      description: ""
74      operationId: "readQuads"
75      parameters:
76      - name: "format"
77        in: "query"
78        description: "Data encoder to use for response. Overrides Accept header."
79        required: false
80        schema:
81          type: "string"
82          enum:
83          - "nquads"
84          - "jsonld"
85          - "json"
86          - "json-stream"
87          - "pquads"
88          - "graphviz"
89          - "gml"
90          - "graphml"
91          default: "nquads"
92      responses:
93        200:
94          description: "read successful"
95          content:
96            'application/n-quads':
97              schema:
98                $ref: '#/components/schemas/NQuads'
99            'application/ld+json':
100              schema:
101                $ref: '#/components/schemas/JSONLD'
102            'application/json':
103              schema:
104                $ref: '#/components/schemas/JsonQuads'
105            'application/x-json-stream':
106              schema:
107                $ref: '#/components/schemas/JsonQuadsStream'
108            'application/x-protobuf':
109              schema:
110                $ref: '#/components/schemas/PQuads'
111        default:
112          description: "Unexpected error"
113          content:
114            application/json:
115              schema:
116                $ref: '#/components/schemas/Error'
117  /api/v2/write:
118    post:
119      tags:
120      - "data"
121      summary: "Writes quads to the database"
122      description: ""
123      operationId: "writeQuads"
124      requestBody:
125        description: "File in one of formats specified in Content-Type."
126        required: true
127        content:
128          'application/n-quads':
129            schema:
130              $ref: '#/components/schemas/NQuads'
131          'application/ld+json':
132            schema:
133              $ref: '#/components/schemas/JSONLD'
134          'application/json':
135            schema:
136              $ref: '#/components/schemas/JsonQuads'
137          'application/x-json-stream':
138            schema:
139              $ref: '#/components/schemas/JsonQuadsStream'
140          'application/x-protobuf':
141            schema:
142              $ref: '#/components/schemas/PQuads'
143      parameters:
144      - name: "format"
145        in: "query"
146        description: "Data decoder to use for request. Overrides Content-Type."
147        required: false
148        schema:
149          type: "string"
150      responses:
151        200:
152          description: "write successful"
153          content:
154            application/json:
155              schema:
156                type: "object"
157                properties:
158                  result:
159                    type: "string"
160                    description: "legacy success message"
161                  count:
162                    type: "integer"
163                    description: "number of quads received"
164        default:
165          description: "Unexpected error"
166          content:
167            application/json:
168              schema:
169                $ref: '#/components/schemas/Error'
170  /api/v2/node/delete:
171    post:
172      tags:
173      - "data"
174      summary: "Removes a node add all associated quads"
175      description: ""
176      operationId: "deleteNode"
177      requestBody:
178        description: "File in one of formats specified in Content-Type."
179        required: true
180        content:
181          'application/n-quads':
182            schema:
183              $ref: '#/components/schemas/NQuadsNode'
184          'application/json':
185            schema:
186              $ref: '#/components/schemas/JsonNode'
187          'application/x-protobuf':
188            schema:
189              $ref: '#/components/schemas/PNode'
190      parameters:
191      - name: "format"
192        in: "query"
193        description: "Data decoder to use for request. Overrides Content-Type."
194        required: false
195        schema:
196          type: "string"
197      responses:
198        200:
199          description: "delete successful"
200          content:
201            application/json:
202              schema:
203                type: "object"
204                properties:
205                  result:
206                    type: "string"
207                    description: "legacy success message"
208                  count:
209                    type: "integer"
210                    description: "number of nodes deleted"
211        default:
212          description: "Unexpected error"
213          content:
214            application/json:
215              schema:
216                $ref: '#/components/schemas/Error'
217  /api/v2/delete:
218    post:
219      tags:
220      - "data"
221      summary: "Delete quads from the database"
222      description: ""
223      operationId: "deleteQuads"
224      requestBody:
225        description: "File in one of formats specified in Content-Type."
226        required: true
227        content:
228          'application/n-quads':
229            schema:
230              $ref: '#/components/schemas/NQuads'
231          'application/ld+json':
232            schema:
233              $ref: '#/components/schemas/JSONLD'
234          'application/json':
235            schema:
236              $ref: '#/components/schemas/JsonQuads'
237          'application/x-json-stream':
238            schema:
239              $ref: '#/components/schemas/JsonQuadsStream'
240          'application/x-protobuf':
241            schema:
242              $ref: '#/components/schemas/PQuads'
243      parameters:
244      - name: "format"
245        in: "query"
246        description: "Data decoder to use for request. Overrides Content-Type."
247        required: false
248        schema:
249          type: "string"
250      responses:
251        200:
252          description: "write successful"
253          content:
254            application/json:
255              schema:
256                type: "object"
257                properties:
258                  result:
259                    type: "string"
260                    description: "legacy success message"
261                  count:
262                    type: "integer"
263                    description: "number of quads received"
264        default:
265          description: "Unexpected error"
266          content:
267            application/json:
268              schema:
269                $ref: '#/components/schemas/Error'
270  /api/v2/query:
271    get:
272      tags:
273      - "queries"
274      summary: "Query the graph"
275      description: ""
276      operationId: "query"
277      parameters:
278      - name: "lang"
279        in: "query"
280        description: "Query language to use"
281        required: true
282        schema:
283          type: "string"
284          enum:
285          - "gizmo"
286          - "graphql"
287          - "mql"
288          - "sexp"
289      requestBody:
290        description: "Query text"
291        required: true
292        content:
293          '*/*':
294            schema:
295              type: "string"
296            examples:
297              gizmo:
298                summary: "Gizmo: first 10 nodes"
299                value: "g.V().GetLimit(10)"
300              graphql:
301                summary: "GraphQL: first 10 nodes"
302                value: "{\n  nodes(first: 10){\n    id\n  }\n}"
303      responses:
304        200:
305          description: "query succesful"
306          content:
307            'application/json':
308              schema:
309                oneOf:
310                - type: "array"
311                - type: "object"
312        default:
313          description: "Unexpected error"
314          content:
315            application/json:
316              schema:
317                $ref: '#/components/schemas/Error'
318  /gephi/gs:
319    get:
320      tags:
321      - "queries"
322      summary: "Gephi GraphStream endpoint"
323      description: ""
324      operationId: "gephiGraphStream"
325      parameters:
326      - name: "mode"
327        in: "query"
328        description: "Streamer mode"
329        required: false
330        schema:
331          type: "string"
332          enum:
333          - "raw"
334          - "nodes"
335          default: "raw"
336      - name: "limit"
337        in: "query"
338        description: "Limit the number of nodes or quads"
339        required: false
340        schema:
341          type: "integer"
342      responses:
343        200:
344          description: "success"
345          content:
346            'application/stream+json':
347              schema:
348                type: "string"
349                format: "binary"
350                description: "stream of JSON objects"
351        default:
352          description: "Unexpected error"
353          content:
354            application/json:
355              schema:
356                $ref: '#/components/schemas/Error'
357components:
358  schemas:
359    NQuads:
360      type: "string"
361      format: "binary"
362      example: |
363        <alice> <follows> <bob> .
364        <bob> <follows> <fred> .
365        <bob> <status> "cool_person" .
366        <charlie> <follows> <bob> .
367        <charlie> <follows> <dani> .
368        <dani> <follows> <bob> .
369        <dani> <follows> <greg> .
370        <dani> <status> "cool_person" .
371        <emily> <follows> <fred> .
372        <fred> <follows> <greg> .
373        <greg> <status> "cool_person" .
374        <predicates> <are> <follows> .
375        <predicates> <are> <status> .
376        <emily> <status> "smart_person" <smart_graph> .
377        <greg> <status> "smart_person" <smart_graph> .
378    NQuadsNode:
379      type: "string"
380      format: "binary"
381      example: "<alice>"
382    JSONLD:
383      type: "string"
384      format: "binary"
385      example: {
386          "@context": "http://schema.org/",
387          "@type": "Person",
388          "name": "Jane Doe",
389          "jobTitle": "Professor",
390          "telephone": "(425) 123-4567",
391          "url": "http://www.janedoe.com"
392        }
393      externalDocs:
394        url: 'https://json-ld.org'
395    JsonQuad:
396      type: "object"
397      properties:
398        subject:
399          type: "string"
400        predicate:
401          type: "string"
402        object:
403          type: "string"
404        label:
405          type: "string"
406    JsonQuads:
407      type: "array"
408      items:
409        type: "object"
410        properties:
411          subject:
412            type: "string"
413          predicate:
414            type: "string"
415          object:
416            type: "string"
417          label:
418            type: "string"
419    JsonNode:
420      type: "string"
421    JsonQuadsStream:
422      type: "string"
423      format: "binary"
424      description: "stream of JsonQuad objects"
425    PQuads:
426      type: "string"
427      format: "binary"
428      description: "Cayley-specific binary encoding of quads based on protobuf"
429    PNode:
430      type: "string"
431      format: "binary"
432      description: "Cayley-specific binary encoding of node value based on protobuf"
433    Error:
434      type: "object"
435      properties:
436        error:
437          type: "string"
438          description: "error message"