summaryrefslogtreecommitdiffstats
path: root/docs/api-reference/api-doc-template.rst
blob: 54e587fd644f775ab02f74706eb9d30b8544c795 (plain)
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
.. This work is licensed under a Creative Commons Attribution 4.0
.. International License. http://creativecommons.org/licenses/by/4.0
.. Copyright (C) 2020 Deutsche Telekom AG.


.. This is a template to document new APIs for CDS blueprint processor

.. make use of tabs whenever it fits

Module
====================

Resource 1
------------

General description about the resource.


Method 1 Endpoint 1
~~~~~~~~~~~~~~~~~~~~

<method> ``<path>``
......................

Method 1 Endpoint 1 description

Request
...........

.. code-block:: curl
   :caption: **(sample) request**

   request command

.. can be split into Header and Body description if thats more suitable.
.. If its split, Header requires content-type definition, Body requires example payload

**Request Path Parameters:**

.. list-table::
   :widths: 20 20 20 40
   :header-rows: 1

   * - Parameter
     - Type
     - Required
     - Description
   * - value 1
     - value 2
     - value 3
     - value 4
   * - value 1
     - value 2
     - value 3
     - value 4

**Request Query Parameters:**

.. list-table::
   :widths: 20 20 20 40
   :header-rows: 1

   * - Parameter
     - Type
     - Required
     - Description
   * - value 1
     - value 2
     - value 3
     - value 4
   * - value 1
     - value 2
     - value 3
     - value 4

**Request Body Parameters:**

.. list-table::
   :widths: 20 20 20 40
   :header-rows: 1

   * - Parameter
     - Type
     - Required
     - Description
   * - value 1
     - value 2
     - value 3
     - value 4
   * - value 1
     - value 2
     - value 3
     - value 4

Success Response(s)
......................

HTTP Status 202 OK

Headers:
``Content-Type:application/json``

.. code-block:: json
   :caption: **(sample) response body and/or response schema**

   (sample) response (can be {})

**Success Response Parameters:**

.. list-table::
   :widths: 30 30 40
   :header-rows: 1

   * - Parameter
     - Type
     - Description
   * - value 1
     - value 2
     - value 3
   * - value 1
     - value 2
     - value 3

Error Response(s)
......................

HTTP Status 404 The requested resource could not be found

.. code-block:: json
   :caption: **sample error response**

   error response

**Error Response Parameters:**

.. list-table::
   :widths: 30 30 40
   :header-rows: 1

   * - Parameter
     - Type
     - Description
   * - value 1
     - value 2
     - value 3
   * - value 1
     - value 2
     - value 3

.. or just table for responses with HTTP code, description and schema

Consumes
............

``application/json``

Produces
...........

``application/json``


Functional Description
..............................

What does the API do in detail?

Technical Description
...........................

Called class, methods, other hints.

Related topics
......................

 * Topic 1
 * Topic 2


Method 2 Endpoint 1
~~~~~~~~~~~~~~~~~~~~

<method> ``<path>``
......................

Method 2 Endpoint 1 description

..


Method 1 Endpoint 2 (Subresource):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<method> ``<path><subpath>``
..............................


..

Resource 2
--------------------


..