pymacaron/pymacaron/ping.yaml at master · pymacaron/pymacaron · GitHub

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
# This is a swagger description of the PyMacaron default API

swagger: '2.0'
info:
  title: Tthe PyMacaron default API
  version: "0.0.1"
  description: |
    Implement the /ping and /version endpoints common to all services.

host: localhost
# array of all schemes that your API supports
schemes:
  - https
  - http
# will be prefixed to all paths
basePath: /v1
produces:
  - application/json
paths:

  /ping:
    get:
      summary: Ping the server.
      description: |
        Return an empty json message (a pong).
      tags:
        - Ping
      produces:
        - application/json
      x-bind-server: pymacaron.api.do_ping
      responses:
        '200':
          description: Ok.
          schema:
            $ref: '#/definitions/Ok'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Error'


  /version:
    get:
      summary: Get the API's version.
      description: |
        Return the API''s version and various stats. Can be used to ping the api.
      tags:
        - Version
      produces:
        - application/json
      x-bind-server: pymacaron.api.do_version
      responses:
        '200':
          description: API version
          schema:
            $ref: '#/definitions/Version'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Error'


  /auth/version:
    get:
      summary: Get the API's version (requires authentication)
      description: |
        Same as '/version', but requiring authentication. Usefull to test your JWT tokens.
      tags:
        - Version
      produces:
        - application/json
      x-bind-server: pymacaron.api.do_version
      x-decorate-server: pymacaron.auth.requires_auth
      responses:
        '200':
          description: API version
          schema:
            $ref: '#/definitions/Version'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Error'


definitions:

  Version:
    type: object
    description: The api''s version
    properties:
      name:
        type: string
        description: Name of this microservice
      version:
        type: string
        description: Version of the docker contained running the api
      apis:
        type: array
        description: Name of the apis implemented by this microservice
        items:
          type: string
      pym_env:
        type: string
        description: Content of PYM_ENV in the container
    example:
      version: 'master-20160215-1903-42-e469af'
      name: 'macaron'
      apis: ['bar', 'foo']
      pym_env: 'helloworld-staging'


  Ok:
    type: object
    description: An empty all-went-well reply
    properties:
      ok:
        type: string


  Error:
    type: object
    description: An api error
    properties:
      status:
        type: integer
        format: int32
        description: HTTP error code.
      error:
        type: string
        description: A unique identifier for this error.
      error_description:
        type: string
        description: A humanly readable error message in the user''s selected language.
      error_id:
        type: string
        description: Unique error id for querying error trace and analytics data
      error_caught:
        type: string
        description: The internal error that was caught (if any)
      user_message:
        type: string
        description: A user-friendly error message, in the user's language, to be shown in the app's alert.
    required:
      - status
      - error
      - error_description
    example:
      status: 500
      error: SERVER_ERROR
      error_description: Expected data to send in reply but got none
      user_message: Something went wrong! Try again later.