vmware / Nsxraml
Labels
NSX for vSphere RAML
This repository holds a RAML specification of the NSX for vSphere 6.x API. For more details on RAML, please visit http://raml.org.
This RAML file has been generated from information that can be found in the "NSX vSphere API Guide" documentation that is available in PDF format at vmware.com.
The purpose of this package is to be used as the basis in building dynamic API clients for the NSX for vSphere API and for the automatic generation of API documentation.
An example of one such dynamic client that uses the NSX RAML specification is the Python 'nsxramlclient' that can be found at: http://github.com/vmware/nsxramlclient
In addition to the RAML file itself, several artifacts are provided that are generated by the tools raml2html, raml2md, raml-fleece and raml2postman:
- In /html-version/ there is a dynamic HTML file generated by raml2html that can be viewed in a browser. There is also a static HTML file generated by raml-fleece that can be converted to a single page PDF documentation file.
- Likewise, /md-version/ contains a markdown file generated by raml2md.
- Finally, in /postman-collection/ there are postman collection and postman environments files generated by raml2postman
You can find more information on the raml2html and raml2md tools on Kevin Renkser's Github https://github.com/kevinrenskers
Details on raml2postman can be found on postmanlabs github https://github.com/postmanlabs/raml2postman
Style
For display names please use the following verbs:
- List - Read a collection of objects. HTTP GET
- Read - Read a single object. HTTP GET
- Create - Create an object. HTTP POST
- Update - Update an object. HTTP PUT
- Delete - Delete an object. HTTP DELETE
- Execute - Execute an action. Example: start a traceroute
- Toggle - Switch the state of a value that is true/false or on/off
Building
If you are interested in building the artifacts you will need a modified version of raml2html and raml2postman. To install these globally use the following commands:
npm install -g https://github.com/yfauser/raml2html
npm install -g https://github.com/yfauser/raml2postman
Note that if you want a local install do not supply the -g argument.
You will also need to install some additional packages. To install it globally use the following commands:
npm install -g janrain/raml-fleece
npm install -g raml2md
In some systems you may also have to manually install the following:
npm install -g commander
npm install -g node-uuid
npm install -g postman_validator
npm install -g raml-parser
npm install -g lodash
npm install -g async
Once the pre-requisites packages are installed you can run the following script:
create_artifacts.sh
Branching and Release
Each major or minor release train of NSX for vSphere in a major.minor.patch versioning scheme will be a branch in this project. These are considered stable for that release train. Example: 6.3 will be a branch.
For each generally available (GA) release of the NSX for vSphere platform there will be a GitHub release (tag) of this project that is named to match the GA version of NSX for vSphere using the major.minor.patch (e.g. 6.2.7) numbering system.
The master branch is considered the development branch for new updates and features. It may or may not be stable.
Support Lifecycle
The supported versions of this project match the supported versions of the NSX for vSphere platform. For specific dates please see the VMware Lifecycle Product Matrix here:
Credits
Special credits and thanks go to Conner Mullaney. He has created more than 80% of the original content in the RAML File out of the NSX-v 6.1.4 API Documentation available as PDF, and with this effort brought this project forward significantly.
License
Copyright © 2015-2018 VMware, Inc. All Rights Reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.