{"id":19632956,"url":"https://github.com/sitewhere/sitewhere-rest-api","last_synced_at":"2025-04-28T07:30:41.564Z","repository":{"id":31818452,"uuid":"170225717","full_name":"sitewhere/sitewhere-rest-api","owner":"sitewhere","description":"JavaScript model and REST API calls for interacting with a SiteWhere instance","archived":false,"fork":false,"pushed_at":"2022-11-10T14:19:12.000Z","size":289,"stargazers_count":3,"open_issues_count":4,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-05T07:33:00.381Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sitewhere.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-12T00:37:12.000Z","updated_at":"2025-02-12T06:38:03.000Z","dependencies_parsed_at":"2023-01-14T19:50:45.614Z","dependency_job_id":null,"html_url":"https://github.com/sitewhere/sitewhere-rest-api","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitewhere%2Fsitewhere-rest-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitewhere%2Fsitewhere-rest-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitewhere%2Fsitewhere-rest-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitewhere%2Fsitewhere-rest-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sitewhere","download_url":"https://codeload.github.com/sitewhere/sitewhere-rest-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251271082,"owners_count":21562487,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T12:15:50.944Z","updated_at":"2025-04-28T07:30:40.174Z","avatar_url":"https://github.com/sitewhere.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SiteWhere REST API\n\nThe [SiteWhere](https://sitewhere.io/) REST API library provides a complete\nTypeScript implementation of the core SiteWhere object model along with comprehensive\nsupport for accessing all system functionality via strongly-typed APIs. This \nmeans you get syntax completion for all core SiteWhere APIs including the\nobjects passed to and received from the interactions when using editors such\nas Visual Studio Code.\n\nThe SiteWhere REST APIs are packaged as a Node.js module and are available\nvia NPM (https://www.npmjs.com/package/sitewhere-rest-api). Install the APIs \ninto an existing Node-enabled project by issuing the following command:\n\n```npm install --save sitewhere-rest-api```\n\nAfter installation, the API elements may be imported individually along with\nvarious parts of the object model. For instance, the code below authenticates\nwith the SiteWhere server to get a JWT, then sends an authenticated call for \ncreating a device on the default tenant:\n\n```typescript\nimport * as SiteWhere from \"sitewhere-rest-api\";\nimport { AxiosResponse, AxiosInstance } from \"axios\";\nimport { IDeviceCreateRequest, IDevice } from \"sitewhere-rest-api\";\n\nasync function createDevice() {\n  // Create Axios instance with basic auth for getting JWT.\n  let auth: AxiosInstance = SiteWhere.Auth.createBasicAuthRequestForCredentials(\n    \"http://localhost:8080/sitewhere/authapi\",\n    \"admin\",\n    \"password\"\n  );\n\n  // Extract JWT.\n  let jwtResp: AxiosResponse\u003cany\u003e = await SiteWhere.AuthAPI.Jwt.getJwt(auth);\n  let jwt: string = jwtResp.headers[\"x-sitewhere-jwt\"];\n\n  // Create Axios instance with JWT and tenant auth information.\n  let axios: AxiosInstance = SiteWhere.Auth.createJwtRequest(\n    \"http://localhost:8080/sitewhere/api\",\n    jwt,\n    \"default\",\n    \"sitewhere01234567890\"\n  );\n\n  // Create request for new device.\n  let request: IDeviceCreateRequest = {\n    deviceTypeToken: \"ipad\",\n    token: \"123-TEST-4989485938\",\n    comments: \"Created via REST API\"\n  };\n\n  // Send device create message and use response.\n  let resp: AxiosResponse\u003cIDevice\u003e = await SiteWhere.API.Devices.createDevice(\n    axios,\n    request\n  );\n  let device: IDevice = resp.data;\n  console.log(`Created ${device.token} on ${device.createdDate}`);\n}\n\ncreateDevice();\n\n```\n\n## Getting a JSON Web Token for Authentication\nIn order to use any of the SiteWhere APIs, a JWT must first be obtained using\nHTTP basic authentication to establish the identity of a system user making\nthe call. The logic below obtains a JWT for user `admin` with password\n`password`. The JWT has a limited lifetime which is determined on the \nSiteWhere server that issues it. New JWTs may be obtained at any time since\nthere is little-or-no server overhead for creating new ones.\n\n```typescript\n  // Create Axios instance with basic auth for getting JWT.\n  let auth: AxiosInstance = SiteWhere.Auth.createBasicAuthRequestForCredentials(\n    \"http://localhost:8080/sitewhere/authapi\",\n    \"admin\",\n    \"password\"\n  );\n\n  // Extract JWT.\n  let jwtResp: AxiosResponse\u003cany\u003e = await SiteWhere.AuthAPI.Jwt.getJwt(auth);\n  let jwt: string = jwtResp.headers[\"x-sitewhere-jwt\"];\n````\nNote that since the code uses `await`, this block would need to be nested\nin an `async` function. As an alternative, standard promise-based access\nis also supported.\n\n## Issuing API Calls for Specific Tenants\nSince SiteWhere is a multitenant system, API calls must specify the tenant\nand associated authentication token in order to access the tenant-specific APIs.\nBefore issuing API calls, create an Axios context. The example shown below\nwill access the `default` tenant with authentication token `sitewhere0123456789`:\n\n```typescript\n  // Create Axios instance with JWT and tenant auth information.\n  let axios: AxiosInstance = SiteWhere.Auth.createJwtRequest(\n    \"http://localhost:8080/sitewhere/api\",\n    jwt,\n    \"default\",\n    \"sitewhere0123456789\"\n  );\n```\n\nThe same Axios context may be reused any number of times as long as the included\nJWT is still valid. If accessing multiple tenants, a separate context should be\ncreated for each tenant.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsitewhere%2Fsitewhere-rest-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsitewhere%2Fsitewhere-rest-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsitewhere%2Fsitewhere-rest-api/lists"}