Discovery Endpoint

The /api endpoint provides an entrance to the API that allows you to browse and discover the resources that the API exposes. This endpoint does not require authentication, however, if API keys are provided the response will include user specific data. The examples below assume that API keys are provided in the request.

GET

URL: /api[/version/]

Arguments Required Purpose
format optional specify the encoding for the response, defaults to JSON
Response  
HTTP Code 200
Content-type application/json
Body  

Example Usage

GET /api/1.0?format=json:

{
  "endpoints": {
    "xmmpDomainControl": {
      "description": "Start, stop, apply ACLs, or get status of an XMPP domain",
      "documentationUrl": "http://chatmongers.com/docs/",
      "httpMethods": {
        "GET": {
          "baseUri": "/api/1.0/xmppdomains",
          "description": "Execute control actions against an XMPP domain",
          "httpParameters": {},
          "returns": "Returns current status or success of an action",
          "signatureUri": "/api/1.0/xmppdomains/<fqdn>/[action]",
          "urlArguments": {
            "action": "perform any of: start, stop, status, aclupdate; defaults to status",
            "fqdn": "the fqdn of the xmpp domain, required"
          }
        }
      }
    },
    "xmmpUserAcl": {
      "description": "Work directly with XMPP user ACLs",
      "documentationUrl": "http://chatmongers.com/docs/",
      "httpMethods": {
        "GET": {
          "baseUri": "/api/1.0/xmppdomains",
          "description": "Get the current ACL for an  XMPP user",
          "httpParameters": {},
          "returns": "Returns the current ACL object",
          "signatureUri": "/api/1.0/xmppdomains/<fqdn>/users/<username>/acl",
          "urlArguments": {
            "fqdn": "the fqdn of the xmpp domain, required",
            "username": "the username identifying the object to apply the ACL to, required"
          }
        },
        "POST": {
          "baseUri": "/api/1.0/xmppdomains",
          "description": "Create a new XMPP user ACL, overwriting any existing ACL",
          "httpParameters": {},
          "returns": "A success response and link to the updated object",
          "signatureUri": "/api/1.0/xmppdomains/<fqdn>/users/<username>/acl",
          "urlArguments": {
            "fqdn": "the fqdn of the xmpp domain, required",
            "username": "the username identifying the object to apply the ACL to, required"
          }
        }
      }
    },
    "xmppDomains": {
      "baseUri": "/api/1.0/xmppdomains",
      "description": "Work with XMPP domains",
      "documentationUrl": "http://chatmongers.com/docs/",
      "httpMethods": {
        "GET": {
          "baseUri": "/api/1.0/xmppdomains",
          "description": "List XMPP domains",
          "httpParameters": {
            "format": {
              "default": "json",
              "description": "the serialization format of the response",
              "required": false,
              "validParameters": [
                "json"
              ]
            },
            "limit": {
              "default": 10,
              "description": "the maximum number of results to return",
              "required": false,
              "validParameters": []
            },
            "offset": {
              "default": null,
              "description": "the XMPP domain after which the result set should begin",
              "required": false,
              "validParameters": []
            }
          },
          "resourceUri": "/api/1.0/xmppdomains",
          "returns": "A list of all XMPP domains available",
          "signatureUri": "/api/1.0/xmppdomains"
        },
        "POST": {
          "baseUri": "/api/1.0/xmppdomains",
          "description": "Provision a new XMPP domain",
          "httpParameters": {},
          "resourceUri": "/api/1.0/xmppdomains",
          "returns": "a success response",
          "signatureUri": "/api/1.0/xmppdomains/[fqdn]",
          "urlArguments": {
            "exampleUri": "/api/1.0/xmppdomains/example.customer.com",
            "fqdn": "the fqdn of the new domain, if not present a random chatwith.it subdomain is provisioned"
          }
        }
      }
    },
    "xmppGateway": {
      "description": "Inject XMPP messages into an XMPP domain via HTTP",
      "documentationUrl": "http://chatmongers.com/docs/",
      "httpMethods": {
        "POST": {
          "baseUri": "/api/1.0/xmppdomains",
          "description": "Create a new XMPP message to be injected into the chat server",
          "httpParameters": {},
          "returns": "A success response",
          "signatureUri": "/api/1.0/xmppdomains/<fqdn>/gateway/messages/[from]",
          "urlArguments": {
            "fqdn": "the fqdn of the xmpp domain, required",
            "from": "the XMPP user that should be the sender, optional for JSON formatted messages, required for XML message stanzas"
          }
        }
      }
    },
    "xmppUsers": {
      "DELETE": {
        "baseUri": "/api/1.0/xmppdomains",
        "description": "Delete an XMPP user",
        "httpParameters": {},
        "returns": "A success response and link to the updated object",
        "signatureUri": "/api/1.0/xmppdomains/<fqdn>/users/<username>",
        "urlArguments": {
          "fqdn": "the fqdn of the xmpp domain, required",
          "username": "the username identifying the object to delete, required"
        }
      },
      "UPDATE": {
        "baseUri": "/api/1.0/xmppdomains",
        "description": "Update an existing user",
        "httpParameters": {
          "format": {
            "default": "json",
            "description": "the serialization format of the response",
            "required": false,
            "validParameters": [
              "json"
            ]
          }
        },
        "returns": "A success response and link to the updated object",
        "signatureUri": "/api/1.0/xmppdomains/<fqdn>/users/<username>",
        "urlArguments": {
          "fqdn": "the fqdn of the xmpp domain, required",
          "username": "the username identifying the object to update, required"
        }
      },
      "description": "Work with XMPP users",
      "documentationUrl": "http://chatmongers.com/docs/",
      "httpMethods": {
        "GET": {
          "baseUri": "/api/1.0/xmppdomains",
          "description": "Get a list of XMPP users for a domain",
          "httpParameters": {
            "format": {
              "default": "json",
              "description": "the serialization format of the response",
              "required": false,
              "validParameters": [
                "json"
              ]
            },
            "limit": {
              "default": 10,
              "description": "the maximum number of results to return",
              "required": false,
              "validParameters": []
            },
            "offset": {
              "default": null,
              "description": "the XMPP user after which the result set should begin",
              "required": false,
              "validParameters": []
            }
          },
          "returns": "A list of XMPP users in a domain",
          "signatureUri": "/api/1.0/xmppdomains/<fqdn>/users"
        },
        "POST": {
          "baseUri": "/api/1.0/xmppdomains",
          "description": "Create a new XMPP user",
          "httpParameters": {
            "password": {
              "default": null,
              "description": "the password to use, if not present a random password will be generated and returned",
              "required": false,
              "validParameters": []
            }
          },
          "returns": "a success response",
          "signatureUri": "/api/1.0/xmppdomains/<fqdn>/users/[username]",
          "urlArguments": {
            "fqdn": "the fqdn of the xmpp domain",
            "username": "the username to use, if not present a random username will be generated"
          }
        }
      },
      "userLists": [
        {
          "resourceUri": "/api/1.0/xmppdomains/example1.chatwith.it/users?format=json",
          "xmppDomain": "example1.chatwith.it"
        },
        {
          "resourceUri": "/api/1.0/xmppdomains/example2.chatwith.it/users?format=json",
          "xmppDomain": "example2.chatwith.it"
        }
      ]
    }
  },
  "resourceUri": "/api/1.0?format=json"
}