DDOC-4: added two new beginner docs and refreshed another #6756
Conversation
|
|
||
| ## How do I Get Started? | ||
|
|
||
| KAZOO is open-core, meaning that you are free to clone, modify, or otherwise utilize the [kazoo-core](https://www.github.com/2600hz/kazoo-core) source code. If you’re interested in building KAZOO from source, this [guide](https://github.com/2600hz/kazoo/blob/master/doc/installation.md) is an appropriate jump-off point. Otherwise, visit our [website](http://2600hz.com) to get in contact about scheduling a demo. |
There was a problem hiding this comment.
"Open core" has nothing to do with the kazoo-core repo, for the record.
There was a problem hiding this comment.
Also links should be to the docs site version of the installation guide and not the repo, right?
|
|
||
| KAZOO is open-core, meaning that you are free to clone, modify, or otherwise utilize the [kazoo-core](https://www.github.com/2600hz/kazoo-core) source code. If you’re interested in building KAZOO from source, this [guide](https://github.com/2600hz/kazoo/blob/master/doc/installation.md) is an appropriate jump-off point. Otherwise, visit our [website](http://2600hz.com) to get in contact about scheduling a demo. | ||
|
|
||
| We at 2600Hz also offer production-grade applications as well as KAZOO cluster hosting and management as services. Visit our [website](http://2600hz.com) for more information. All our guides will assume that you have a KAZOO environment to develop against, whether you’re an open source user or a 2600Hz customer. |
|
|
||
| Almost all requests and responses to the KAZOO API are serialized using JSON, unless otherwise specified in the documentation. You may find, for example, an endpoint will respond with XML instead of JSON. | ||
|
|
||
| The KAZOO API is built on widely-adopted architectures and specifications such as REST (for API consistency) or [JSON-Schema](http://json-schema.org/) (for data validation). You can use any HTTP client to interact with the API, whether via a programming language’s HTTP library, a HTTP GUI like Postman, or just plain old cURL in the terminal. There is very little overhead in order to get started making requests against your KAZOO account. |
There was a problem hiding this comment.
The disrespect on cURL's name with "just plain old"...
There was a problem hiding this comment.
The intention was that cURL is the "barebones" approach! I can change it to "ol' reliable" if you'd like ;)
|
|
||
| ## KAZOO Versioning and API Consistency | ||
|
|
||
| Expect to encounter inconsistencies with official documentation material if you are using features or KAZOO versions that are outside of what we use in our own stable commercial environments. This means that, if you are for example running an older (or newer experimental) version of KAZOO, that this documentation may not be accurate for your given environment. We recommend using our [community forums](https://forums.2600hz.com/forums/) to ask questions. |
There was a problem hiding this comment.
Second sentence is awkwardly constructed
| **index.html** | ||
|
|
||
| ```html | ||
| <head> |
There was a problem hiding this comment.
I assume it might be helpful to package the snippets in this doc into a complete HTML/JS/CSS/whatever set of files so folks can download them to modify at their leisure?
There was a problem hiding this comment.
Somewhere like doc/user_guides/code_examples/ ?
|
|
||
| Since pagination can be turned off by a client-supplied query string parameter, it is important that KAZOO still protect itself from overly large datasets being loaded. Examples seen include large CDR listings, call recording listings, and ledger listings. | ||
| 1. `/{RESOURCE}/{RESOURCE_ID}` | ||
| - A resource, such as `devices`, `users`, `callflows`, et cetera. |
There was a problem hiding this comment.
So you should probably not use resource here as in KAZOO a resource represents upstream carrier configs.
We generically call them collection and entity, so accounts is the collection, {ACCOUNT_ID} is the entity.
Cleaning up some docs and staging some to be put on docs.2600hz.com :)
Part of an initiative to revamp our documentation experience. PRs merged for this purpose are short-term, since docs are still built from the KAZOO monorepo.