OpenAPI

2025-05-24 02:14:21 -04:00 · 2024-06-06 15:27:54 +10:00 · 2024-06-06 15:27:54 +10:00 · 7801635568
commit 7801635568
parent a9c1357689
6 changed files with 1822 additions and 1716 deletions
--- a/openapi/api-docs.yaml
+++ b/openapi/api-docs.yaml
--- a/openapi/components/parameters.yaml
+++ b/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
--- a/openapi/components/schemas/company_settings.yaml
+++ b/openapi/components/schemas/company_settings.yaml
--- a/openapi/info.yaml
+++ b/openapi/info.yaml
@ -38,7 +38,39 @@ info:
              <p style="padding:10px; color: #DBDBDB;"">Production: https://invoicing.co</p>
              <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'
-    description: |
+  -  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'
-    description: |
+  -  url: 'https://invoicing.co'
+     description: |
          ## Production API endpoint
--- a/openapi/misc/misc.yaml
+++ b/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.
--- a/openapi/paths/clients.yaml
+++ b/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:\