├── .editorconfig ├── .gitignore ├── Gemfile ├── Gemfile.lock ├── LICENSE ├── README.md ├── package.json ├── src └── api.apib └── validate.js /.editorconfig: -------------------------------------------------------------------------------- 1 | # EditorConfig helps developers define and maintain consistent 2 | # coding styles between different editors and IDEs 3 | # editorconfig.org 4 | 5 | root = true 6 | 7 | [*] 8 | indent_style = space 9 | indent_size = 4 10 | end_of_line = lf 11 | charset = utf-8 12 | trim_trailing_whitespace = true 13 | insert_final_newline = true 14 | 15 | [*.js] 16 | indent_size = 2 17 | 18 | [*.md, *.apib] 19 | trim_trailing_whitespace = false 20 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | *.log 3 | npm-debug.log* 4 | 5 | # Compiled specification 6 | build 7 | 8 | # Dependency directories 9 | node_modules -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source 'https://rubygems.org' 2 | gem 'apiaryio' 3 | -------------------------------------------------------------------------------- /Gemfile.lock: -------------------------------------------------------------------------------- 1 | GEM 2 | remote: https://rubygems.org/ 3 | specs: 4 | addressable (2.5.0) 5 | public_suffix (~> 2.0, >= 2.0.2) 6 | apiaryio (0.7.0) 7 | json (~> 1.8) 8 | launchy (~> 2.4) 9 | listen (~> 2.0) 10 | rack (~> 1.6.4) 11 | rest-client (~> 1.8) 12 | thor (~> 0.19.1) 13 | celluloid (0.16.0) 14 | timers (~> 4.0.0) 15 | domain_name (0.5.20161129) 16 | unf (>= 0.0.5, < 1.0.0) 17 | ffi (1.9.17) 18 | hitimes (1.2.4) 19 | http-cookie (1.0.3) 20 | domain_name (~> 0.5) 21 | json (1.8.6) 22 | launchy (2.4.3) 23 | addressable (~> 2.3) 24 | listen (2.10.1) 25 | celluloid (~> 0.16.0) 26 | rb-fsevent (>= 0.9.3) 27 | rb-inotify (>= 0.9) 28 | mime-types (2.99.3) 29 | netrc (0.11.0) 30 | public_suffix (2.0.5) 31 | rack (1.6.5) 32 | rb-fsevent (0.9.8) 33 | rb-inotify (0.9.8) 34 | ffi (>= 0.5.0) 35 | rest-client (1.8.0) 36 | http-cookie (>= 1.0.2, < 2.0) 37 | mime-types (>= 1.16, < 3.0) 38 | netrc (~> 0.7) 39 | thor (0.19.4) 40 | timers (4.0.4) 41 | hitimes 42 | unf (0.1.4) 43 | unf_ext 44 | unf_ext (0.0.7.2) 45 | 46 | PLATFORMS 47 | ruby 48 | 49 | DEPENDENCIES 50 | apiaryio 51 | 52 | BUNDLED WITH 53 | 1.14.3 54 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2017 Jakub Synowiec 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![Dev dependencies][dependencies-badge]][dependencies] 2 | 3 | [![Node.js version][nodejs-badge]][nodejs] 4 | [![NPM version][npm-badge]][npm] 5 | [![Ruby version][ruby-badge]][ruby] 6 | [![Bundler version][bundler-badge]][bundler] 7 | 8 | [![MIT License][license-badge]][LICENSE] 9 | [![Roadmap][roadmap-badge]][roadmap] 10 | [![PRs Welcome][prs-badge]][prs] 11 | [![Donate][donate-badge]][donate] 12 | 13 | [![Watch on GitHub][github-watch-badge]][github-watch] 14 | [![Star on GitHub][github-star-badge]][github-star] 15 | [![Tweet][twitter-badge]][twitter] 16 | 17 | # api-blueprint-boilerplate 18 | 19 | Minimalistic boilerplate to quick-start API specification using [API Blueprint][api-blueprint] description language. 20 | 21 | Provides a basic template for REST API documentation that contains some best practices for a pragmatic RESTful API and a set of tools to validate API Blueprint schema or export specification to HTML files. 22 | 23 | Sample project is available in Apary: http://docs.apiblueprintboilerplate.apiary.io/ 24 | 25 | ## Quick start 26 | 27 | This project requires [Node.js][nodejs] 6.2+, [NPM][npm], [Ruby][ruby] and [Bundler][bundler]. So just make sure you have those installed. Then just type following commands: 28 | 29 | ``` 30 | git clone https://github.com/jsynowiec/api-blueprint-boilerplate 31 | cd api-blueprint-boilerplate 32 | npm install 33 | bundle install 34 | npm start 35 | ``` 36 | 37 | You now have a local preview server available at [http://localhost:8080](http://localhost:8080) that is validating and rendering your blueprint using [Apiary CLI][apiaryio-cli]. 38 | 39 | ## Testing against specification 40 | 41 | To test the blueprint run `npm test` command. This will validate the schema using Drafter.js library. 42 | 43 | ## Export HTML files 44 | 45 | To compile the blueprint run `npm run build`. Files will be written to the `build` directory. 46 | 47 | ## Publishing to Apiary 48 | 49 | To publish your blueprint to [Apiary.io][apiaryio] you have to set two environment variables: 50 | 51 | ``` 52 | export APIARY_API_KEY="" 53 | export APIARY_API_NAME="" 54 | ``` 55 | 56 | After that, you can run `npm run publish` command to upload your blueprint to Apiary project. You can also provide those two values before the command 57 | 58 | ``` 59 | APIARY_API_KEY="" APIARY_API_NAME="" npm run publish 60 | ``` 61 | 62 | ## Resources 63 | 64 | * [API Blueprint][api-blueprint], 65 | * [API Blueprint Specification][api-blueprint-specification], 66 | * [MSON Specification][mson-specification], 67 | * [VS Code API Elements extension][vscode-apielements], 68 | * [Apiary.io][apiaryio], 69 | * [Drafter.js][drafterjs], 70 | 71 | ## License 72 | MIT License. See the [LICENSE](https://github.com/jsynowiec/api-blueprint-boilerplate/blob/master/LICENSE) 73 | file. 74 | 75 | [dependencies-badge]: https://david-dm.org/jsynowiec/api-blueprint-boilerplate/dev-status.svg?style=flat-square 76 | [dependencies]: https://david-dm.org/jsynowiec/api-blueprint-boilerplate?type=dev 77 | [nodejs-badge]: https://img.shields.io/badge/node->=%206.2.x-blue.svg?style=flat-square 78 | [nodejs]: https://nodejs.org/dist/latest-v6.x/docs/api/ 79 | [npm-badge]: https://img.shields.io/badge/npm->=%203.x-blue.svg?style=flat-square 80 | [npm]: https://docs.npmjs.com/ 81 | [ruby-badge]: https://img.shields.io/badge/ruby->=%202.x-blue.svg?style=flat-square 82 | [ruby]: http://ruby-doc.org/ 83 | [bundler-badge]: https://img.shields.io/badge/bundler-latest-blue.svg?style=flat-square 84 | [bundler]: http://bundler.io/docs.html 85 | [license-badge]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square 86 | [license]: https://github.com/jsynowiec/api-blueprint-boilerplate/blob/master/LICENSE 87 | [roadmap-badge]: https://img.shields.io/badge/%F0%9F%93%94-roadmap-CD9523.svg?style=flat-square 88 | [roadmap]: https://github.com/jsynowiec/api-blueprint-boilerplate/wiki/Roadmap 89 | [prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square 90 | [prs]: http://makeapullrequest.com 91 | [donate-badge]: https://img.shields.io/badge/€-support-green.svg?style=flat-square 92 | [donate]: https://paypal.me/jaqb/5eur 93 | [github-watch-badge]: https://img.shields.io/github/watchers/jsynowiec/api-blueprint-boilerplate.svg?style=social 94 | [github-watch]: https://github.com/jsynowiec/api-blueprint-boilerplate/watchers 95 | [github-star-badge]: https://img.shields.io/github/stars/jsynowiec/api-blueprint-boilerplate.svg?style=social 96 | [github-star]: https://github.com/jsynowiec/api-blueprint-boilerplate/stargazers 97 | [twitter]: https://twitter.com/intent/tweet?text=Check%20out%20the%20%40apiblueprint%20boilerplate!%20https://github.com/jsynowiec/api-blueprint-boilerplate%20%F0%9F%91%8D 98 | [twitter-badge]: https://img.shields.io/twitter/url/https/jsynowiec/api-blueprint-boilerplate.svg?style=social 99 | [api-blueprint]: https://apiblueprint.org/ 100 | [api-blueprint-specification]: https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md 101 | [apiaryio]: http://apiary.io 102 | [apiaryio-cli]: https://help.apiary.io/tools/apiary-cli/ 103 | [drafterjs]: https://github.com/apiaryio/drafter.js 104 | [mson-specification]: https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md 105 | [vscode-apielements]: https://github.com/XVincentX/vscode-apielements 106 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "api-blueprint-boilerplate", 3 | "version": "1.0.2", 4 | "description": "API Blueprint boilerplate with Drafter.js schema validation and Apiary CLI included", 5 | "engines": { 6 | "node": ">=6.2.0" 7 | }, 8 | "devDependencies": { 9 | "api-blueprint-validator-module": "~1.2.2", 10 | "markdown-styles": "^3.1.9", 11 | "rimraf": "^2.5.4", 12 | "yargs": "^6.6.0" 13 | }, 14 | "scripts": { 15 | "setup": "mkdir build", 16 | "clean": "rimraf build", 17 | "build": "npm run clean && npm run setup && npm run build:blueprint && npm run build:raw", 18 | "build:blueprint": "apiary preview --path=\"src/api.apib\" --output=\"build/api.html\"", 19 | "build:raw": "cp src/api.apib ./api.md && generate-md --layout github --input ./api.md --output build/raw && rm ./api.md", 20 | "test": "node validate.js --files 'src/**/*.apib'", 21 | "start": "apiary preview --path=\"src/api.apib\" --server --port 8080", 22 | "publish": "apiary publish --api-name=\"${APIARY_API_NAME}\" --path=\"src/api.apib\"" 23 | }, 24 | "repository": { 25 | "type": "git", 26 | "url": "https://github.com/jsynowiec/api-blueprint-boilerplate" 27 | }, 28 | "author": { 29 | "name": "Jakub Synowiec", 30 | "email": "jakub@jakubsynowiec.info", 31 | "url": "https://jakubsynowiec.info" 32 | }, 33 | "license": "MIT", 34 | "bugs": { 35 | "url": "https://github.com/jsynowiec/api-blueprint-boilerplate/issues" 36 | }, 37 | "homepage": "https://github.com/jsynowiec/api-blueprint-boilerplate#readme" 38 | } 39 | -------------------------------------------------------------------------------- /src/api.apib: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # YOUR AWESOME API NAME 4 | 5 | *This API blueprint is subject to change due to technology restrictions, performance optimizations or changing requirements.* 6 | 7 | ## Authentication 8 | 9 | + This API uses [JWT](http://jwt.io/) for authentication. 10 | + Every token MUST be refreshed before its expiration time. 11 | + Token MUST be provided in `Authorization` header. 12 | + Token MUST be provided for each request that requires authentication. 13 | + This API issues a **long-lived access tokens** for consumers. A long-lived JWT generally SHOULD last about **30 days**. If no requests are made, the token MUST expire and the user MUST log in again to get a new one. 14 | 15 | > A custom scheme like "JWT" seems to be more appropriate than coercing the OAuth2 Bearer scheme. 16 | 17 | ### Example Header 18 | ``` 19 | Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhNnZoQW8zRkc3dDEiLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE0NzA1OTg5NzIsImV4cCI6MTQ3MDY4NTM3Mn0.ltA9zZmJKszBJuuV7pTWtY7LzLXrRUfebJDhy_jGMeM 20 | ``` 21 | 22 | ### Claims 23 | + `exp` - The exp ( *expiration time* ) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. 24 | + `iat` - The iat ( *issued at* ) claim identifies the time at which the JWT was issued. 25 | + `sub` - The aud ( *audience* ) claim identifies the subject of this token (for e.g. a user id). 26 | + `iss` - The iss ( *issuer* ) claim identifies the principal that issued the JWT. 27 | 28 | ## Consumer Identification 29 | 30 | This API uses `User-Agent` and `Application-Id` headers to identify API consumer. `Application-Id` MUST contain an UUID that uniquely identifies a particular consumer installation. 31 | 32 | ### Example Headers 33 | ``` 34 | User-Agent: Mozilla/5.0 (Linux; Android 4.4; Nexus 5 Build/_BuildID_) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/30.0.0.0 Mobile Safari/537.36 35 | Application-Id: 6454d937-0a18-44a8-b482-bb48684f1ed4 36 | ``` 37 | 38 | ## Filtering, Ordering, Pagination & Searching 39 | 40 | ### Filtering 41 | 42 | This API can filter returned collections based on provided query parameters. Virtually any model field can be used as a filter. 43 | 44 | For example, when requesting a list of movies from the /movies endpoint, you may want to limit these to only those of drama genre. This could be accomplished with a request like `GET /movies?genre=drama`. Here, genre is a query parameter that implements a filter. 45 | 46 | ### Ordering 47 | 48 | This API can sort returned collections. A generic query parameter `sort` is used to describe sorting rules. This parameter can take a list of comma separated field, each with a possible unary negative to imply descending sort order. 49 | 50 | E.g. `GET /movies?sort=-rating` - Retrieves a list of movies in descending order of user rating. 51 | 52 | By default all resources are ordered by their creation time, from newest to oldest. 53 | 54 | ### Pagination 55 | 56 | This API uses the [Link header - RFC 5988](http://tools.ietf.org/html/rfc5988#page-6) to include pagination details. 57 | 58 | An example of a Link header is described in [GitHub documentation](https://developer.github.com/guides/traversing-with-pagination/). 59 | 60 | This API returns total count of paged resources in `Total-Count` HTTP header. 61 | 62 | ### Searching 63 | 64 | This API uses a generic parameter `search` to expose a full text search mechanism. 65 | 66 | ## HTTP Methods 67 | 68 | This API uses HTTP verbs (methods) as following: 69 | 70 | + `GET` - *Read* - used to **read** (or retrieve) a representation of a resource. 71 | + `POST` - *Create* - used to **create** new resources. In particular, it's used to create subordinate resources. 72 | + `PUT` - *Update/Replace* - used for **update** capabilities, PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource. On successful request, replaces identified resource with the request body. 73 | + `PATCH` - *Update/Modify* - used for **modify** capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource. 74 | + `DELETE` - *Delete* - used to **delete** a resource identified by a URI. 75 | 76 | ## Localization 77 | 78 | This API uses `Accept-Language` header to identify the locale. 79 | 80 | `Accept-Language: en` 81 | 82 | This header SHOULD be present in every request. If not, API MUST use the **english** language/locale. 83 | 84 | ## Media Type 85 | 86 | Where applicable this API MUST use the JSON media-type. Requests with a message-body are using plain JSON to set or update resource states. 87 | 88 | `Content-type: application/json` and `Accept: application/json` headers SHOULD be set on all requests if not stated otherwise. 89 | 90 | ## Notational Conventions 91 | 92 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119). 93 | 94 | ## Representation of Date and Time 95 | 96 | All exchange of date and time-related data MUST be done according to ISO 8601 standard and stored in UTC. 97 | 98 | When returning date and time-related data `YYYY-MM-DDThh:mm:ss.SSSZ` format MUST be used. 99 | 100 | ## Resource IDs 101 | 102 | This API uses short non-sequential url-friendly unique ids. Every resource id MUST consists of 9 url-friendly characters: `A-Z`, `a-z`, `0-9`, `_` and `-`. 103 | 104 | ### Example 105 | `a6vhAo3FG7t1` 106 | 107 | ## Status Codes and Errors 108 | 109 | This API uses HTTP status codes to communicate with the API consumer. 110 | 111 | + `200 OK` - Response to a successful GET, PUT, PATCH or DELETE. 112 | + `201 Created` - Response to a POST that results in a creation. 113 | + `204 No Content` - Response to a successful request that won't be returning a body (like a DELETE request). 114 | + `400 Bad Request` - Malformed request; form validation errors. 115 | + `401 Unauthorized` - When no or invalid authentication details are provided. 116 | + `403 Forbidden` - When authentication succeeded but authenticated user doesn't have access to the resource. 117 | + `404 Not Found` - When a non-existent resource is requested. 118 | + `405 Method Not Allowed` - Method not allowed. 119 | + `406 Not Acceptable` - Could not satisfy the request Accept header. 120 | + `415 Unsupported Media Type` - Unsupported media type in request. 121 | 122 | ### Error response 123 | 124 | This API returns both, machine-readable error codes and human-readable error messages in response body when an error is encountered. 125 | 126 | #### Example 127 | 128 | ##### Validation Error 129 | 130 | ```js 131 | { 132 | "statusCode": 400, 133 | "error": "Bad Request", 134 | "message": "Invalid query parameters", 135 | "data": { 136 | "code": 10003, 137 | "validation": { 138 | "details":[ 139 | { 140 | "message": "\"name\" is required", 141 | "path": "name", 142 | "type": "any.required", 143 | "context": { 144 | "key": "name" 145 | } 146 | },{ 147 | "message": "\"email\" must be a valid email", 148 | "path": "email", 149 | "type": "string.email", 150 | "context": { 151 | "value": "foo", 152 | "key": "email" 153 | } 154 | } 155 | ], 156 | "source": "query", 157 | "keys": [ "name","email" ] 158 | } 159 | } 160 | } 161 | ``` 162 | 163 | ##### Generic Error 164 | 165 | ```js 166 | { 167 | "statusCode": 403, 168 | "error": "Forbidden", 169 | "message": "Your account is suspended and is not permitted to access this feature", 170 | "data": { 171 | "code": 13003 172 | } 173 | } 174 | ``` 175 | 176 | #### Error Codes Dictionary 177 | 178 | + `10003` - Invalid query parameters 179 | + `10005` - Date is not in ISO 8601 standard 180 | + `10010` - Invalid Content-Type 181 | + `10011` - Invalid User-Agent 182 | + `10012` - Invalid or missing Application-Id 183 | + `11001` - Invalid or expired token 184 | + `11003` - Bad authentication data - *Method requires authentication but it was not presented or was wholly invalid.* 185 | + `11005` - Account not allowed to access this endpoint 186 | + `13003` - Your account is suspended and is not permitted to access this feature 187 | 188 | ## Versioning 189 | 190 | This API uses `Api-Version` header to identify requested version. Every **minor** version SHOULD be backward compatible. However, **major** versions MAY introduce *breaking changes*. 191 | 192 | `Api-Version: 1.0.0` 193 | 194 | This header SHOULD be present in every request. If not, API MUST use the newest available major release. 195 | 196 | If requested version is not available, API SHOULD try to fall back to the next available minor release. 197 | 198 | # Group Authentication 199 | 200 | ## User login [/auth/login] 201 | 202 | Access tokens are required to access nearly all endpoints of this API. 203 | 204 | ### Retrieve a token [POST] 205 | 206 | Allows to retrieve a valid JSON Web Token for username and password. 207 | 208 | **Endpoint information** 209 | 210 | | | | 211 | |-------------------------|----| 212 | | Requires authentication | No | 213 | | Has restricted scope | No | 214 | 215 | + Request (application/json) 216 | + Attributes 217 | + login: `john.doe@mail.com` (string, required) - User email address 218 | + password: `QXR0mi38a2` (string, required) - User password 219 | 220 | + Response 200 (application/json) 221 | + Attributes 222 | + token: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....` (string) - JSON Web Token. 223 | 224 | ## Refresh a token [POST /auth/refresh-token] 225 | 226 | Allows to retrieve a new, valid JSON Web Token based on a valid JSON Web Token. 227 | 228 | Expired tokens MUST NOT be refreshed. 229 | 230 | **Endpoint information** 231 | 232 | | | | 233 | |-------------------------|-----| 234 | | Requires authentication | Yes | 235 | | Has restricted scope | No | 236 | 237 | + Request 238 | + Headers 239 | 240 | Authorization: JWT 241 | 242 | + Response 200 (application/json) 243 | + Attributes 244 | + token: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....` (string) - New JWT 245 | 246 | ## User registration [/auth/register] 247 | 248 | ### Register a new user [POST] 249 | 250 | Creates a new user account. 251 | 252 | + Provided email address MUST be unique. 253 | + Passwords MUST have at least six characters. 254 | + Passwords MUST NOT contain the user name or parts of the user’s full name, such as his first name. 255 | + Passwords MUST use at least three of the four available character types: lowercase letters, uppercase letters, numbers, and symbols. 256 | 257 | After successful registration a confirmation email MUST be sent to provided address. 258 | 259 | **Endpoint information** 260 | 261 | | | | 262 | |-------------------------|----| 263 | | Requires authentication | No | 264 | 265 | **Error codes** 266 | 267 | | | | | 268 | |-------|--------|--------------------------------------------| 269 | | `400` | `4001` | Password doesn't match password guidelines | 270 | | `400` | `3001` | User already exists | 271 | 272 | + Request (application/json) 273 | + Attributes 274 | + email: `john.doe@mail.com` (string, required) - E-mail address. 275 | + password: `QXR0mi38a2` (string, required) - User password. 276 | 277 | + Response 201 278 | 279 | # Group User 280 | 281 | ## Current user profile [/users/me] 282 | 283 | Current user MUST be identifed by JWT provided in request header. 284 | 285 | ### Retrieve profile of the current user [GET] 286 | 287 | Retrieves the profile of the current user. 288 | 289 | **Endpoint information** 290 | 291 | | | | 292 | |-------------------------|-----| 293 | | Requires authentication | Yes | 294 | | Has restricted scope | No | 295 | 296 | + Request 297 | + Headers 298 | 299 | Authorization: JWT 300 | 301 | + Response 200 (application/json) 302 | + Attributes (User) 303 | 304 | ### Partialy update a profile of the current user [PATCH] 305 | 306 | Updates the profile of the current user setting the values of the parameters passed. Any parameters not provided will be left unchanged. 307 | 308 | **Endpoint information** 309 | 310 | | | | 311 | |-------------------------|-----| 312 | | Requires authentication | Yes | 313 | | Has restricted scope | No | 314 | 315 | + Request (application/json) 316 | + Headers 317 | 318 | Authorization: JWT 319 | + Attributes 320 | + name: `Ben` (string) - First name of the user. 321 | 322 | + Response 200 (application/json) 323 | + Attributes (User) 324 | 325 | ## User password [/users/me/password] 326 | 327 | ### Change a password of the current user [PUT] 328 | 329 | Changes user password. 330 | 331 | After password is changed all access tokens issued for this user prior to password change must be invalidated. 332 | 333 | **Endpoint information** 334 | 335 | | | | 336 | |-------------------------|-----| 337 | | Requires authentication | Yes | 338 | | Has restricted scope | No | 339 | 340 | **Error codes** 341 | 342 | | | | | 343 | |-------|--------|--------------------------------------------| 344 | | `400` | `4001` | Password doesn't match password guidelines | 345 | 346 | + Request (application/json) 347 | + Headers 348 | 349 | Authorization: JWT 350 | + Attributes 351 | + old_password: `secret` (string, required) 352 | + new_password: `$3C6e7` (string, required) 353 | 354 | + Response 200 355 | + Attributes 356 | + token: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` (string) - New JSON Web Token. 357 | 358 | ## User avatar [/users/me/avatar] 359 | 360 | ### Set user avatar [POST] 361 | 362 | Sets user avatar. 363 | 364 | Either upload the raw binary ( **media** parameter) of the file, or its base64-encoded contents ( **media_data** parameter). Use raw binary when possible, because base64 encoding results in larger file sizes. 365 | 366 | **Endpoint information** 367 | 368 | | | | 369 | |-------------------------|-----| 370 | | Requires authentication | Yes | 371 | | Has restricted scope | No | 372 | 373 | **Error codes** 374 | 375 | | | | | 376 | |-------|--------|-----------------------| 377 | | `400` | `2001` | File is too large | 378 | | `400` | `2002` | Unsupported file type | 379 | 380 | + Request (multipart/form-data) 381 | + Headers 382 | 383 | Authorization: JWT 384 | 385 | + Response 200 386 | + Attributes 387 | + avatar: `https://...` (string) - Public download URL 388 | 389 | ### Delete user avatar [DELETE] 390 | 391 | Restores user avatar to the default one. 392 | 393 | **Endpoint information** 394 | 395 | | | | 396 | |-------------------------|-----| 397 | | Requires authentication | Yes | 398 | | Has restricted scope | No | 399 | 400 | + Request 401 | + Headers 402 | 403 | Authorization: JWT 404 | 405 | + Response 204 406 | 407 | ## Users [/users] 408 | 409 | ### List all users [GET] 410 | 411 | Returns a list of users. The users are returned in sorted order, with the most recently created user accounts appearing first. 412 | 413 | | | | 414 | |-------------------------|-----| 415 | | Requires authentication | Yes | 416 | | Has restricted scope | No | 417 | 418 | + Request 419 | + Headers 420 | 421 | Authorization: JWT 422 | 423 | + Response 200 (application/json) 424 | + Attributes (array[User]) 425 | 426 | ## User [/users/{id}] 427 | 428 | + Parameters 429 | + id: `a6vhAo3FG7t1` (string) - id of the user. 430 | 431 | ### Retrieve a user [GET] 432 | 433 | Retrieves the details of an existing user. 434 | 435 | | | | 436 | |-------------------------|-----| 437 | | Requires authentication | Yes | 438 | | Has restricted scope | No | 439 | 440 | **Error codes** 441 | 442 | | | | | 443 | |-------|--------|-------------------------------| 444 | | `400` | `1000` | Referenced resource not found | 445 | 446 | + Request 447 | + Headers 448 | 449 | Authorization: JWT 450 | 451 | + Response 200 (application/json) 452 | + Attributes (User) 453 | 454 | + Response 404 455 | 456 | # Data Structures 457 | 458 | ## Resource (object) 459 | + id: `a6vhAo3FG7t1` (string, fixed) - Short non-sequential url-friendly unique id. 460 | + createdAt: `2016-07-01T15:11:09.553Z` (string) - ISO Date/time string. When this resource was created. 461 | + updatedAt: `2016-07-01T15:11:09.553Z` (string) - ISO Date/time string. When this resource was last updated. 462 | 463 | ## User (Resource) 464 | + email: `john.doe@mail.com` (string, required) - Login. Unique email address of the user. 465 | + facebookId: `888047057953991` (number, optional, nullable) - Facebook ID of the user if user account is linked to the Facebook account. 466 | + name: `John` (string, optional, nullable) - First name of the user. 467 | + surname: `Doe` (string, optional, nullable) - Last name of the user. 468 | + avatar (string, optional, nullable) - URL to user avatar. 469 | -------------------------------------------------------------------------------- /validate.js: -------------------------------------------------------------------------------- 1 | const validator = require('api-blueprint-validator-module'); 2 | const argv = require('yargs') 3 | .usage('Usage: $0 --files [str]') 4 | .demand(['files']) 5 | .argv; 6 | 7 | (({ files, failOnWarnings = true} = {}) => validator.parseAndValidateFiles(files, failOnWarnings))(argv); 8 | --------------------------------------------------------------------------------