OpenAPI

openapi/api-docs.yaml

@@ -39,6 +39,38 @@ info:
               <p style="padding:10px; color: #DBDBDB;">Demo: https://demo.invoiceninja.com</p>
           </div>
 
+          ## Client Libraries
+
+          PHP SDK can be found [here](https://github.com/invoiceninja/sdk-php)
+
+          ## Authentication:
+
+          Invoice Ninja uses API tokens to authenticate requests. You can view and manage your API keys in Settings > Account Management > Integrations > API tokens
+
+          API requests must be made over HTTPS. Calls made to HTTP will fail.
+
+          ## Errors:
+
+          Invoice Ninja uses standard HTTP response codes to indicate the success or failure of a request. below is a table of standard status codes and responses
+
+          | Status Code | Explanation                                                                 |
+          |-------------|-----------------------------------------------------------------------------|
+          | 200         | OK: The request has succeeded. The information returned with the response is dependent on the method used in the request. |
+          | 301         | Moved Permanently: This and all future requests should be directed to the given URI. |
+          | 303         | See Other: The response to the request can be found under another URI using the GET method. |
+          | 400         | Bad Request: The server cannot or will not process the request due to an apparent client error. |
+          | 401         | Unauthorized: Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. |
+          | 403         | Forbidden: The request was valid, but the server is refusing action. |
+          | 404         | Not Found: The requested resource could not be found but may be available in the future. |
+          | 405         | Method Not Allowed: A request method is not supported for the requested resource. |
+          | 409         | Conflict: Indicates that the request could not be processed because of conflict in the request. |
+          | 422         | Unprocessable Entity: The request was well-formed but was unable to be followed due to semantic errors. |
+          | 429         | Too Many Requests: The user has sent too many requests in a given amount of time ("rate limiting"). |
+          | 500         | Internal Server Error: A generic error message, given when an unexpected condition was encountered and no more specific message is suitable. |
+
+          ## Pagination
+
+          When using index routes to retrieve lists of data, by default we limit the number of records returned to 20. You can using standard pagination to paginate results, ie:
   termsOfService: 'https://invoiceninja.github.io/docs/legal/terms_of_service/#page-content'
   contact:
     email: contact@invoiceninja.com
@@ -49,13 +81,11 @@ info:
     url: 'https://www.elastic.co/licensing/elastic-license'
   version: 5.9.2
 servers:
-  - title: demo
+  -  url: 'https://demo.invoiceninja.com'
-    url: 'https://demo.invoiceninja.com'
      description: |
           ## Demo API endpoint 
           You can use the demo API key `TOKEN` to test the endpoints from within this API spec
-  - title: production
+  -  url: 'https://invoicing.co'
-    url: 'https://invoicing.co'
      description: |
           ## Production API endpoint
 paths:
@@ -12031,6 +12061,20 @@ paths:
       tags:
         - clients
       summary: 'List clients'
+      x-badges:
+        - color: blue
+          label: core
+      x-code-samples:
+      - lang: javascript
+        source: |
+          fetch('/example')
+            .then(response => response.json())
+            .then(data => console.log(data));
+      x-custom-element:
+            type: markdown
+            value: |
+              ### Custom Response Description
+              This is a custom description for the response returned by the `/example` endpoint.
       description: |
             When retrieving a list of clients you can also chain query parameters in order to filter the dataset that is returned. For example, you can send a request to the following URL to retrieve clients that have a balance greater than 1000:\
               
@@ -14535,16 +14579,16 @@ components:
       examples:
         user:
           value: user
-          summary: include=user will include the user object in the response
+          summary: include=user will include the Cser object in the response
         company:
           value: company
-          summary: include=company will include the company object in the response
+          summary: include=company will include the Company object in the response
         token:
           value: token
-          summary: include=token will include the token object in the response
+          summary: include=token will include the Company Token object in the response
         account:
           value: account
-          summary: include=account will include the account object in the response
+          summary: include=account will include the Account object in the response
     per_page_meta:
       name: per_page
       in: query
@@ -14572,7 +14616,15 @@ components:
     include_static:
       name: include_static
       in: query
-      description: 'Returns static variables'
+      description: |
+        Static variables include:
+          - Currencies
+          - Countries 
+          - Languages
+          - Payment Types
+          - Email Templatees
+          - Industries
+
       required: false
       schema:
         type: string
@@ -14580,7 +14632,11 @@ components:
     clear_cache:
       name: clear_cache
       in: query
-      description: 'Clears the static cache'
+      description: |
+        Clears cache
+
+        Sometimes after a system update where the static variables have been updated, it may be necessary to clear the cache so that the static variables repopulate  
+
       required: false
       schema:
         type: string
@@ -16313,7 +16369,7 @@ components:
         token:
           $ref: '#/components/schemas/CompanyToken'
       type: object
-CompanySettings:
+    CompanySettings:
         required:
             - currency_id
         properties:
@@ -21616,9 +21672,6 @@ CompanySettings:
           example: true
       type: object
 tags:
-  - name: overview
-    description: |
-      System overview
   - name: login
     description: |
       Attempts to authenticate with the API using a email/password combination.

openapi/components/parameters.yaml

@@ -123,16 +123,16 @@
       examples:
         user:
           value: user
-          summary: include=user will include the user object in the response
+          summary: include=user will include the Cser object in the response
         company:
           value: company
-          summary: include=company will include the company object in the response
+          summary: include=company will include the Company object in the response
         token:
           value: token
-          summary: include=token will include the token object in the response
+          summary: include=token will include the Company Token object in the response
         account:
           value: account
-          summary: include=account will include the account object in the response
+          summary: include=account will include the Account object in the response
     per_page_meta:
       name: per_page
       in: query
@@ -160,7 +160,15 @@
     include_static:
       name: include_static
       in: query
-      description: 'Returns static variables'
+      description: |
+        Static variables include:
+          - Currencies
+          - Countries 
+          - Languages
+          - Payment Types
+          - Email Templatees
+          - Industries
+
       required: false
       schema:
         type: string
@@ -168,7 +176,11 @@
     clear_cache:
       name: clear_cache
       in: query
-      description: 'Clears the static cache'
+      description: |
+        Clears cache
+
+        Sometimes after a system update where the static variables have been updated, it may be necessary to clear the cache so that the static variables repopulate  
+
       required: false
       schema:
         type: string

openapi/components/schemas/company_settings.yaml

@@ -1,4 +1,4 @@
-CompanySettings:
+    CompanySettings:
         required:
             - currency_id
         properties:

openapi/info.yaml

@@ -39,6 +39,38 @@ info:
               <p style="padding:10px; color: #DBDBDB;">Demo: https://demo.invoiceninja.com</p>
           </div>
 
+          ## Client Libraries
+
+          PHP SDK can be found [here](https://github.com/invoiceninja/sdk-php)
+
+          ## Authentication:
+
+          Invoice Ninja uses API tokens to authenticate requests. You can view and manage your API keys in Settings > Account Management > Integrations > API tokens
+
+          API requests must be made over HTTPS. Calls made to HTTP will fail.
+
+          ## Errors:
+
+          Invoice Ninja uses standard HTTP response codes to indicate the success or failure of a request. below is a table of standard status codes and responses
+
+          | Status Code | Explanation                                                                 |
+          |-------------|-----------------------------------------------------------------------------|
+          | 200         | OK: The request has succeeded. The information returned with the response is dependent on the method used in the request. |
+          | 301         | Moved Permanently: This and all future requests should be directed to the given URI. |
+          | 303         | See Other: The response to the request can be found under another URI using the GET method. |
+          | 400         | Bad Request: The server cannot or will not process the request due to an apparent client error. |
+          | 401         | Unauthorized: Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. |
+          | 403         | Forbidden: The request was valid, but the server is refusing action. |
+          | 404         | Not Found: The requested resource could not be found but may be available in the future. |
+          | 405         | Method Not Allowed: A request method is not supported for the requested resource. |
+          | 409         | Conflict: Indicates that the request could not be processed because of conflict in the request. |
+          | 422         | Unprocessable Entity: The request was well-formed but was unable to be followed due to semantic errors. |
+          | 429         | Too Many Requests: The user has sent too many requests in a given amount of time ("rate limiting"). |
+          | 500         | Internal Server Error: A generic error message, given when an unexpected condition was encountered and no more specific message is suitable. |
+
+          ## Pagination
+
+          When using index routes to retrieve lists of data, by default we limit the number of records returned to 20. You can using standard pagination to paginate results, ie:
   termsOfService: 'https://invoiceninja.github.io/docs/legal/terms_of_service/#page-content'
   contact:
     email: contact@invoiceninja.com
@@ -49,12 +81,10 @@ info:
     url: 'https://www.elastic.co/licensing/elastic-license'
   version: 5.9.2
 servers:
-  - title: demo
+  -  url: 'https://demo.invoiceninja.com'
-    url: 'https://demo.invoiceninja.com'
      description: |
           ## Demo API endpoint 
           You can use the demo API key `TOKEN` to test the endpoints from within this API spec
-  - title: production
+  -  url: 'https://invoicing.co'
-    url: 'https://invoicing.co'
      description: |
           ## Production API endpoint

openapi/misc/misc.yaml

@@ -1,7 +1,4 @@
 tags:
-  - name: overview
-    description: |
-      System overview
   - name: login
     description: |
       Attempts to authenticate with the API using a email/password combination.

openapi/paths/clients.yaml

@@ -3,6 +3,20 @@
       tags:
         - clients
       summary: 'List clients'
+      x-badges:
+        - color: blue
+          label: core
+      x-code-samples:
+      - lang: javascript
+        source: |
+          fetch('/example')
+            .then(response => response.json())
+            .then(data => console.log(data));
+      x-custom-element:
+            type: markdown
+            value: |
+              ### Custom Response Description
+              This is a custom description for the response returned by the `/example` endpoint.
       description: |
             When retrieving a list of clients you can also chain query parameters in order to filter the dataset that is returned. For example, you can send a request to the following URL to retrieve clients that have a balance greater than 1000:\