Skip to content

Commit d2102e1

Browse files
johannesduesingjohannesduesing
committed
Add OpenAPI 3 specification for REST interface
1 parent a4766bc commit d2102e1

File tree

1 file changed

+188
-0
lines changed

1 file changed

+188
-0
lines changed

‎openapi-spec.yaml‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
openapi: "3.0.0"
2+
info:
3+
title: Delphi WebAPI REST Interface
4+
description: This is the documentation for the *Delphi WebAPI Application*, which is part of the Delphi System for querying software artifacts based on statically extracted metrics.
5+
version: 0.9.5
6+
paths:
7+
/version:
8+
get:
9+
tags: ["Administration"]
10+
summary: Retrieves the version of this WebAPI instance
11+
responses:
12+
'200':
13+
description: "Success, returning WebAPI version"
14+
content:
15+
text/plain:
16+
example: "0.9.5"
17+
/features:
18+
get:
19+
tags: ["Queries"]
20+
summary: Retrieves a list of all features available for querying
21+
responses:
22+
'200':
23+
description: Success, returning feature list
24+
content:
25+
application/json:
26+
schema:
27+
type: array
28+
items:
29+
$ref: "#/components/schemas/Feature"
30+
31+
/statistics:
32+
get:
33+
tags: ["Administration"]
34+
summary: Retrieves WebAPI statistics from the ElasticSearch backend
35+
responses:
36+
'200':
37+
description: "Returns statistics regarding the number of indexed artifacts"
38+
content:
39+
application/json:
40+
schema:
41+
$ref: "#/components/schemas/Statistics"
42+
'500':
43+
description: "Internal error while retrieving statistics from ElasticSearch"
44+
45+
/search:
46+
post:
47+
tags: ["Queries"]
48+
summary: Executes a search query and returns matching artifact identifiers
49+
requestBody:
50+
description: "Request containing the query that is to be executed"
51+
required: true
52+
content:
53+
application/json:
54+
schema:
55+
$ref: "#/components/schemas/QueryRequest"
56+
responses:
57+
'200':
58+
description: "Result of the query execution"
59+
content:
60+
application/json:
61+
schema:
62+
$ref: "#/components/schemas/SearchResults"
63+
'500':
64+
description: "Backend error while executing query"
65+
content:
66+
text/plain:
67+
example: "Description of the server error"
68+
69+
/retrieve/{identifier}:
70+
get:
71+
tags: ["Queries"]
72+
summary: Retrieves artifact details for the given identifier
73+
parameters:
74+
- name: identifier
75+
in: path
76+
required: true
77+
schema:
78+
type: string
79+
example: "com.typesafe.akka:akka-actor:1.2.3"
80+
responses:
81+
'200':
82+
description: "Success, returning list of matching artifact information"
83+
content:
84+
application/json:
85+
schema:
86+
type: array
87+
items:
88+
$ref: "#/components/schemas/Artifact"
89+
90+
'404':
91+
description: "Identifier not found on server"
92+
93+
components:
94+
schemas:
95+
Feature:
96+
required:
97+
- name
98+
- description
99+
properties:
100+
name:
101+
type: string
102+
description: "Name to reference this feature with"
103+
example: "metrics.api.jdbc.PreparedStatement"
104+
description:
105+
type: string
106+
description: "Description of the feature"
107+
example: "Creation and execution of java.sql.PreparedStatement."
108+
Statistics:
109+
required:
110+
- total
111+
- hermesEnabled
112+
properties:
113+
total:
114+
type: number
115+
description: "Number of total entries in the index"
116+
example: 6200000
117+
hermesEnabled:
118+
type: number
119+
description: "Number of index entries that have metric results associated to them"
120+
example: 3456000
121+
SearchResults:
122+
required:
123+
- totalHits
124+
- hits
125+
- queried
126+
properties:
127+
totalHits:
128+
type: number
129+
description: "Number of hits for the query that was executed"
130+
example: 3210
131+
hits:
132+
type: array
133+
description: "List of query hits"
134+
items:
135+
$ref: "#/components/schemas/Artifact"
136+
queried:
137+
type: string
138+
description: "Date and time the query was executed at as `ISO8601`"
139+
example: "2004-06-14T23:34:30"
140+
Artifact:
141+
properties:
142+
id:
143+
type: string
144+
description: "Unique identifier of a software artifact"
145+
example: "com.typesafe.akka:akka-actor:1.2.3"
146+
metadata:
147+
$ref: "#/components/schemas/ArtifactMetadata"
148+
metricResults:
149+
type: object
150+
description: Values for all metrics involved in the query
151+
additionalProperties:
152+
type: number
153+
example:
154+
"metrics.api.jdbc.PreparedStatement": 3
155+
ArtifactMetadata:
156+
properties:
157+
source:
158+
type: string
159+
description: "Source of the software artifact"
160+
example: "Maven Central"
161+
discovered:
162+
type: string
163+
description: "Date and time the artifact was discovered at as `ISO8601`"
164+
example: "2004-06-14T23:34:30"
165+
groupId:
166+
type: string
167+
description: "GroupId attribute of a Maven Artifact"
168+
example: "com.typesafe.akka"
169+
artifactId:
170+
type: string
171+
description: "ArtifactId attribut of a Maven Artifact"
172+
example: "akka-actor"
173+
version:
174+
type: string
175+
description: "Version attribute of a Maven Artifact"
176+
example: "1.2.3"
177+
QueryRequest:
178+
required:
179+
- query
180+
properties:
181+
query:
182+
type: string
183+
description: "The query to be executed"
184+
example: '[source] = "Maven" && [metrics.librarymethods] = 0 && [metrics.projectpackages] > 10 && [metrics.projectpackages] < 50'
185+
limit:
186+
type: number
187+
description: "Maximum number of identifiers to return"
188+
example: 50

0 commit comments

Comments
 (0)