README

portainer_api

PortainerApi - JavaScript client for portainer_api Portainer API is an HTTP API served by Portainer. It is used by the Portainer UI and everything you can do with the UI can be done using the HTTP API. Examples are available at https://gist.github.com/deviantony/77026d402366b4b43fa5918d41bc42f8 You can find out more about Portainer at http://portainer.io and get some support on Slack. # Authentication Most of the API endpoints require to be authenticated as well as some level of authorization to be used. Portainer API uses JSON Web Token to manage authentication and thus requires you to provide a token in the Authorization header of each request with the Bearer authentication mechanism. Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE # Security Each API endpoint has an associated access policy, it is documented in the description of each endpoint. Different access policies are available: * Public access * Authenticated access * Restricted access * Administrator access ### Public access No authentication is required to access the endpoints with this access policy. ### Authenticated access Authentication is required to access the endpoints with this access policy. ### Restricted access Authentication is required to access the endpoints with this access policy. Extra-checks might be added to ensure access to the resource is granted. Returned data might also be filtered. ### Administrator access Authentication as well as an administrator role are required to access the endpoints with this access policy. # Execute Docker requests Portainer DO NOT expose specific endpoints to manage your Docker resources (create a container, remove a volume, etc...). Instead, it acts as a reverse-proxy to the Docker HTTP API. This means that you can execute Docker requests via the Portainer HTTP API. To do so, you can use the /endpoints/{id}/docker Portainer API endpoint (which is not documented below due to Swagger limitations). This endpoint has a restricted access policy so you still need to be authenticated to be able to query this endpoint. Any query on this endpoint will be proxied to the Docker API of the associated endpoint (requests and responses objects are the same as documented in the Docker API). NOTE: You can find more information on how to query the Docker API in the Docker official documentation as well as in this Portainer example. This SDK is automatically generated by the Swagger Codegen project:

API version: 1.20.0
Package version: 1.20.0
Build package: io.swagger.codegen.languages.JavascriptClientCodegen

Installation

For Node.js

npm

To publish the library as a npm, please follow the procedure in "Publishing npm packages".

Then install it via:

npm install portainer_api --save

Local development

To use the library locally without publishing to a remote npm registry, first install the dependencies by changing into the directory containing package.json (and this README). Let's call this JAVASCRIPT_CLIENT_DIR. Then run:

npm install

Next, link it globally in npm with the following, also from JAVASCRIPT_CLIENT_DIR:

npm link

Finally, switch to the directory you want to use your portainer_api from, and run:

npm link /path/to/<JAVASCRIPT_CLIENT_DIR>

You should now be able to require('portainer_api') in javascript files from the directory you ran the last command above from.

git

If the library is hosted at a git repository, e.g. https://github.com/YOUR_USERNAME/portainer_api then install it via:

    npm install YOUR_USERNAME/portainer_api --save

For browser

The library also works in the browser environment via npm and browserify. After following the above steps with Node.js and installing browserify with npm install -g browserify, perform the following (assuming main.js is your entry file, that's to say your javascript file where you actually use this library):

browserify main.js > bundle.js

Then include bundle.js in the HTML pages.

Webpack Configuration

Using Webpack you may encounter the following error: "Module not found: Error: Cannot resolve module", most certainly you should disable AMD loader. Add/merge the following section to your webpack config:

module: {
  rules: [
    {
      parser: {
        amd: false
      }
    }
  ]
}

Getting Started

Please follow the installation instruction and execute the following JS code:

var PortainerApi = require('portainer_api');

var api = new PortainerApi.AuthApi()

var body = new PortainerApi.AuthenticateUserRequest(); // {AuthenticateUserRequest} Credentials used for authentication


var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
api.authenticateUser(body, callback);

Documentation for API Endpoints

All URIs are relative to http://portainer.domain/api

Class	Method	HTTP request	Description
PortainerApi.AuthApi	authenticateUser	POST /auth	Authenticate a user
PortainerApi.DockerhubApi	dockerHubInspect	GET /dockerhub	Retrieve DockerHub information
PortainerApi.DockerhubApi	dockerHubUpdate	PUT /dockerhub	Update DockerHub information
PortainerApi.EndpointGroupsApi	endpointGroupAccessUpdate	PUT /endpoint_groups/{id}/access	Manage accesses to an endpoint group
PortainerApi.EndpointGroupsApi	endpointGroupCreate	POST /endpoint_groups	Create a new endpoint
PortainerApi.EndpointGroupsApi	endpointGroupDelete	DELETE /endpoint_groups/{id}	Remove an endpoint group
PortainerApi.EndpointGroupsApi	endpointGroupInspect	GET /endpoint_groups/{id}	Inspect an endpoint group
PortainerApi.EndpointGroupsApi	endpointGroupList	GET /endpoint_groups	List endpoint groups
PortainerApi.EndpointGroupsApi	endpointGroupUpdate	PUT /endpoint_groups/{id}	Update an endpoint group
PortainerApi.EndpointsApi	endpointAccessUpdate	PUT /endpoints/{id}/access	Manage accesses to an endpoint
PortainerApi.EndpointsApi	endpointCreate	POST /endpoints	Create a new endpoint
PortainerApi.EndpointsApi	endpointDelete	DELETE /endpoints/{id}	Remove an endpoint
PortainerApi.EndpointsApi	endpointInspect	GET /endpoints/{id}	Inspect an endpoint
PortainerApi.EndpointsApi	endpointJob	POST /endpoints/{id}/job	Execute a job on the endpoint host
PortainerApi.EndpointsApi	endpointList	GET /endpoints	List endpoints
PortainerApi.EndpointsApi	endpointUpdate	PUT /endpoints/{id}	Update an endpoint
PortainerApi.RegistriesApi	registryAccessUpdate	PUT /registries/{id}/access	Manage accesses to a registry
PortainerApi.RegistriesApi	registryCreate	POST /registries	Create a new registry
PortainerApi.RegistriesApi	registryDelete	DELETE /registries/{id}	Remove a registry
PortainerApi.RegistriesApi	registryInspect	GET /registries/{id}	Inspect a registry
PortainerApi.RegistriesApi	registryList	GET /registries	List registries
PortainerApi.RegistriesApi	registryUpdate	PUT /registries/{id}	Update a registry
PortainerApi.ResourceControlsApi	resourceControlCreate	POST /resource_controls	Create a new resource control
PortainerApi.ResourceControlsApi	resourceControlDelete	DELETE /resource_controls/{id}	Remove a resource control
PortainerApi.ResourceControlsApi	resourceControlUpdate	PUT /resource_controls/{id}	Update a resource control
PortainerApi.SettingsApi	publicSettingsInspect	GET /settings/public	Retrieve Portainer public settings
PortainerApi.SettingsApi	settingsInspect	GET /settings	Retrieve Portainer settings
PortainerApi.SettingsApi	settingsLDAPCheck	PUT /settings/authentication/checkLDAP	Test LDAP connectivity
PortainerApi.SettingsApi	settingsUpdate	PUT /settings	Update Portainer settings
PortainerApi.StacksApi	stackCreate	POST /stacks	Deploy a new stack
PortainerApi.StacksApi	stackDelete	DELETE /stacks/{id}	Remove a stack
PortainerApi.StacksApi	stackFileInspect	GET /stacks/{id}/file	Retrieve the content of the Stack file for the specified stack
PortainerApi.StacksApi	stackInspect	GET /stacks/{id}	Inspect a stack
PortainerApi.StacksApi	stackList	GET /stacks	List stacks
PortainerApi.StacksApi	stackMigrate	POST /stacks/{id}/migrate	Migrate a stack to another endpoint
PortainerApi.StacksApi	stackUpdate	PUT /stacks/{id}	Update a stack
PortainerApi.StatusApi	statusInspect	GET /status	Check Portainer status
PortainerApi.TagsApi	tagCreate	POST /tags	Create a new tag
PortainerApi.TagsApi	tagDelete	DELETE /tags/{id}	Remove a tag
PortainerApi.TagsApi	tagList	GET /tags	List tags
PortainerApi.TeamMembershipsApi	teamMembershipCreate	POST /team_memberships	Create a new team membership
PortainerApi.TeamMembershipsApi	teamMembershipDelete	DELETE /team_memberships/{id}	Remove a team membership
PortainerApi.TeamMembershipsApi	teamMembershipList	GET /team_memberships	List team memberships
PortainerApi.TeamMembershipsApi	teamMembershipUpdate	PUT /team_memberships/{id}	Update a team membership
PortainerApi.TeamsApi	teamCreate	POST /teams	Create a new team
PortainerApi.TeamsApi	teamDelete	DELETE /teams/{id}	Remove a team
PortainerApi.TeamsApi	teamInspect	GET /teams/{id}	Inspect a team
PortainerApi.TeamsApi	teamList	GET /teams	List teams
PortainerApi.TeamsApi	teamMembershipsInspect	GET /teams/{id}/memberships	Inspect a team memberships
PortainerApi.TeamsApi	teamUpdate	PUT /teams/{id}	Update a team
PortainerApi.TemplatesApi	templateCreate	POST /templates	Create a new template
PortainerApi.TemplatesApi	templateDelete	DELETE /templates/{id}	Remove a template
PortainerApi.TemplatesApi	templateInspect	GET /templates/{id}	Inspect a template
PortainerApi.TemplatesApi	templateList	GET /templates	List available templates
PortainerApi.TemplatesApi	templateUpdate	PUT /templates/{id}	Update a template
PortainerApi.UploadApi	uploadTLS	POST /upload/tls/{certificate}	Upload TLS files
PortainerApi.UsersApi	userAdminCheck	GET /users/admin/check	Check administrator account existence
PortainerApi.UsersApi	userAdminInit	POST /users/admin/init	Initialize administrator account
PortainerApi.UsersApi	userCreate	POST /users	Create a new user
PortainerApi.UsersApi	userDelete	DELETE /users/{id}	Remove a user
PortainerApi.UsersApi	userInspect	GET /users/{id}	Inspect a user
PortainerApi.UsersApi	userList	GET /users	List users
PortainerApi.UsersApi	userMembershipsInspect	GET /users/{id}/memberships	Inspect a user memberships
PortainerApi.UsersApi	userPasswordCheck	POST /users/{id}/passwd	Check password validity for a user
PortainerApi.UsersApi	userUpdate	PUT /users/{id}	Update a user

Documentation for Models

Documentation for Authorization

jwt

Type: API key
API key parameter name: Authorization
Location: HTTP header

Usage no npm install needed!