1"use strict";(self.webpackChunkmy_website=self.webpackChunkmy_website||[]).push([[5546],{3450:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>o,default:()=>d,frontMatter:()=>s,metadata:()=>r,toc:()=>h});var a=n(5893),i=n(1151);const s={sidebar_position:5,title:"Using the HTTP REST API"},o=void 0,r={id:"getting-started/connect-app/using-the-rest-http-api",title:"Using the HTTP REST API",description:"Hivekit provides a RESTful HTTP API that makes it easy to manage objects, areas, instructions and all other Hivekit concepts from any HTTP environment. You can find its full documentation here. Due to the request-response nature of HTTP, this API does not support subscriptions and realtime data feeds. For these, we recommend an official Hivekit SDK or the use of the Websocket API instead.",source:"@site/tutorials-and-examples/getting-started/connect-app/using-the-rest-http-api.md",sourceDirName:"getting-started/connect-app",slug:"/getting-started/connect-app/using-the-rest-http-api",permalink:"/tutorials-and-examples/getting-started/connect-app/using-the-rest-http-api",draft:!1,unlisted:!1,tags:[],version:"current",sidebarPosition:5,frontMatter:{sidebar_position:5,title:"Using the HTTP REST API"},sidebar:"tutorialSidebar",previous:{title:"Using another programming language or environment",permalink:"/tutorials-and-examples/getting-started/connect-app/using-another-environment-or-programming-language"},next:{title:"Using the Websocket API",permalink:"/tutorials-and-examples/getting-started/connect-app/using-the-websocket-api"}},c={},h=[{value:"Concepts",id:"concepts",level:2},{value:"What we want to do",id:"what-we-want-to-do",level:2},{value:"Step 1: Sign in to Hivekit",id:"step-1-sign-in-to-hivekit",level:2},{value:"Step 2: Look up the <code>create object</code> request",id:"step-2-look-up-the-create-object-request",level:2},{value:"Step 3: Gathering the necessary information",id:"step-3-gathering-the-necessary-information",level:2},{value:"The Realm ID",id:"the-realm-id",level:3},{value:"The Access Token",id:"the-access-token",level:3},{value:"The Object ID",id:"the-object-id",level:3},{value:"Step 4: Create the object",id:"step-4-create-the-object",level:2},{value:"Step 5: Check the object on the map",id:"step-5-check-the-object-on-the-map",level:2},{value:"Step 6: Update the object",id:"step-6-update-the-object",level:2},{value:"Step 7: Read the object",id:"step-7-read-the-object",level:2}];function l(e){const t={a:"a",code:"code",h2:"h2",h3:"h3",img:"img",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,i.a)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsxs)(t.p,{children:["Hivekit provides a RESTful HTTP API that makes it easy to manage objects, areas, instructions and all other Hivekit concepts from any HTTP environment. ",(0,a.jsx)(t.a,{href:"/docs/http-api/usage",children:"You can find its full documentation here"}),". Due to the request-response nature of HTTP, this API does not support subscriptions and realtime data feeds. For these, we recommend an official Hivekit SDK or the use of the ",(0,a.jsx)(t.a,{href:"/tutorials-and-examples/getting-started/connect-app/using-the-websocket-api",children:"Websocket API"})," instead."]}),"\n",(0,a.jsx)(t.p,{children:"Alright, let's get started. If you prefer to watch this tutorial as a video, you can do so below. Otherwise, keep reading for the text version."}),"\n",(0,a.jsx)("iframe",{width:"960",height:"540",src:"https://player.vimeo.com/video/913798476?h=12d7d61bf4&title=0&byline=0&portrait=0",frameborder:"0",allow:"autoplay; fullscreen; picture-in-picture",allowfullscreen:!0}),"\n",(0,a.jsx)(t.h2,{id:"concepts",children:"Concepts"}),"\n",(0,a.jsx)(t.p,{children:"Before we start, let's quickly review the two concepts we'll be working with."}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsxs)(t.li,{children:["\n",(0,a.jsxs)(t.p,{children:["A ",(0,a.jsx)(t.strong,{children:"realm"})," is a space within which something happens, e.g. a city or a building. Realms serve as containers for all other concepts - your vehicles, areas, instructions and tasks all live within the scope of a realm."]}),"\n"]}),"\n",(0,a.jsxs)(t.li,{children:["\n",(0,a.jsxs)(t.p,{children:["An ",(0,a.jsx)(t.strong,{children:"object"})," is a physical or virtual entity that can be tracked and managed. This could be a vehicle, a person, a sensor, a package, a building, a piece of equipment, or anything else you want to keep track of. Objects have a location and optional data."]}),"\n"]}),"\n"]}),"\n",(0,a.jsx)(t.h2,{id:"what-we-want-to-do",children:"What we want to do"}),"\n",(0,a.jsx)(t.p,{children:"In this tutorial, we'll"}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsx)(t.li,{children:"sign in to Hivekit"}),"\n",(0,a.jsx)(t.li,{children:"get an API Endpoint URL, Token and Realm ID"}),"\n",(0,a.jsx)(t.li,{children:"create a new object via HTTP request"}),"\n",(0,a.jsx)(t.li,{children:"check our new object on Hivekit's Map View"}),"\n",(0,a.jsx)(t.li,{children:"read the object"}),"\n",(0,a.jsx)(t.li,{children:"update the object"}),"\n"]}),"\n",(0,a.jsx)(t.h2,{id:"step-1-sign-in-to-hivekit",children:"Step 1: Sign in to Hivekit"}),"\n",(0,a.jsxs)(t.p,{children:["Start by logging into your Hivekit account. If your team needs access, ",(0,a.jsx)(t.a,{href:"https://hivekit.io/contact/",children:"get in touch"}
1)," to discuss your requirements and arrange onboarding."]}),"\n",(0,a.jsx)(t.p,{children:(0,a.jsx)(t.img,{alt:"Hivekit dashboard",src:n(7335).Z+"",width:"1450",height:"940"})}),"\n",(0,a.jsx)(t.p,{children:"Before continuing, ask your Hivekit administrator for the realm ID and access token to use for this tutorial."}),"\n",(0,a.jsxs)(t.h2,{id:"step-2-look-up-the-create-object-request",children:["Step 2: Look up the ",(0,a.jsx)(t.code,{children:"create object"})," request"]}),"\n",(0,a.jsxs)(t.p,{children:["For this tutorial, we want to create an object within our realm that represents a delivery driver. So let's start by looking up the ",(0,a.jsx)(t.code,{children:"create object"})," request in the ",(0,a.jsx)(t.a,{href:"/docs/http-api/object#create-or-update-an-object",children:"HTTP API documentation"}),"."]}),"\n",(0,a.jsxs)(t.p,{children:["Here, we learn that the request is a ",(0,a.jsx)(t.code,{children:"POST"})," request to the ",(0,a.jsx)(t.code,{children:"https://api.hivekit.io/v2/realm/[realmId]/object/[objectId]"})," endpoint. The request body should contain a label to identify the object as well as a location and optional data."]}),"\n",(0,a.jsxs)(t.p,{children:["To authenticate our request, we also need an access token. You can pass this token as a ",(0,a.jsx)(t.a,{href:"/docs/http-api/usage",children:"query parameter, header or as part of the payload"}),". For this tutorial, we'll pass it as a ",(0,a.jsx)(t.code,{children:"Authorization: Bearer <token>"})," header."]}),"\n",(0,a.jsx)(t.h2,{id:"step-3-gathering-the-necessary-information",children:"Step 3: Gathering the necessary information"}),"\n",(0,a.jsx)(t.p,{children:"We need to gather the following information:"}),"\n",(0,a.jsxs)(t.ul,{children:["\n",(0,a.jsx)(t.li,{children:"The Realm ID"}),"\n",(0,a.jsx)(t.li,{children:"The Access Token"}),"\n",(0,a.jsx)(t.li,{children:"The Object ID"}),"\n"]}),"\n",(0,a.jsx)(t.h3,{id:"the-realm-id",children:"The Realm ID"}),"\n",(0,a.jsxs)(t.p,{children:["The realm ID can be found on the Hivekit dashboard, just below the selected realm:\n",(0,a.jsx)(t.img,{alt:"Realm ID",src:n(3264).Z+"",width:"1450",height:"940"})]}),"\n",(0,a.jsx)(t.h3,{id:"the-access-token",children:"The Access Token"}),"\n",(0,a.jsxs)(t.p,{children:['The access token can be found in the "Access Management" section of the Hivekit dashboard.\n',(0,a.jsx)(t.img,{alt:"Access token",src:n(4330).Z+"",width:"1310",height:"931"})]}),"\n",(0,a.jsxs)(t.p,{children:['You can display it and copy its value by clicking "show token".\n',(0,a.jsx)(t.img,{alt:"Access token",src:n(9038).Z+"",width:"770",height:"551"})]}),"\n",(0,a.jsx)(t.h3,{id:"the-object-id",children:"The Object ID"}),"\n",(0,a.jsxs)(t.p,{children:["The object id is something we need to generate when creating the object. You can either use an existing id, e.g. a license plate number for a vehicle or come up with your own. Object IDs allow you to identify an object throughout its lifecycle. For this tutorial, we'll use the id ",(0,a.jsx)(t.code,{children:"rider-12"}),"."]}),"\n",(0,a.jsx)(t.h2,{id:"step-4-create-the-object",children:"Step 4: Create the object"}),"\n",(0,a.jsxs)(t.p,{children:["We now have everything we need to make our HTTP request. We'll use the ",(0,a.jsx)(t.code,{children:"curl"})," command to make the request. If you're using a different programming language, you can use any HTTP library to make the request, as well as de
1sktop clients like Postman or Insomnia."]}),"\n",(0,a.jsx)(t.pre,{children:(0,a.jsx)(t.code,{className:"language-bash",children:'curl -X POST \\\n https://api.hivekit.io/v2/realm/realm-6XmQP7V2grlPAn6nO5I9T/object/rider-12 \\\n -H \'Authorization: Bearer YOUR.ACCESS.TOKEN\' \\\n -H \'Content-Type: application/json\' \\\n -d \'{"label":"Delivery Rider 12","location":{"latitude":52.5240,"longitude":13.397567},"data":{"charge":0.7}}\'\n'})}),"\n",(0,a.jsxs)(t.p,{children:["This command sends a ",(0,a.jsx)(t.code,{children:"POST"})," request to the ",(0,a.jsx)(t.code,{children:"https://api.hivekit.io/v2/realm/realm-6XmQP7V2grlPAn6nO5I9T/object/rider-12"})," endpoint with the access token as a header and the object data as a JSON payload."]}),"\n",(0,a.jsx)(t.h2,{id:"step-5-check-the-object-on-the-map",children:"Step 5: Check the object on the map"}),"\n",(0,a.jsxs)(t.p,{children:["After running the ",(0,a.jsx)(t.code,{children:"curl"})," command, you should see a response like this:"]}),"\n",(0,a.jsx)(t.pre,{children:(0,a.jsx)(t.code,{className:"language-js",children:'{"result": "success"}\n'})}),"\n",(0,a.jsxs)(t.p,{children:["But - who wants to trust that? Let's check if our object really exists. We can do this by visiting the ",(0,a.jsx)(t.a,{href:"https://hivekit.io/account/#/realms",children:"Realms section of the Hivekit dashboard"}),' and clicking on "Go to Realm Map". Here, we should find our new object on the category tree on the left - as well as on the map itself. When we click on the object, we should see its label, location and data.']}),"\n",(0,a.jsx)(t.p,{children:(0,a.jsx)(t.img,{alt:"Map view",src:n(5610).Z+"",width:"1031",height:"499"})}),"\n",(0,a.jsx)(t.h2,{id:"step-6-update-the-object",children:"Step 6: Update the object"}),"\n",(0,a.jsx)(t.p,{children:"Let's send another request, exactly like the one above - but we'll change the location and charge of the object. As soon as the request is sent, you should see the changes reflected on the map."}),"\n",(0,a.jsx)(t.h2,{id:"step-7-read-the-object",children:"Step 7: Read the object"}),"\n",(0,a.jsxs)(t.p,{children:["Finally, we'll read the object's data. This can be done by sending a ",(0,a.jsx)(t.code,{children:"GET"})," request to the same URL as before, with the same ",(0,a.jsx)(t.code,{children:"Authorization"})," header, e.g."]}),"\n",(0,a.jsx)(t.pre,{children:(0,a.jsx)(t.code,{className:"language-bash",children:"curl -X GET \\\n https://api.hivekit.io/v2/realm/realm-6XmQP7V2grlPAn6nO5I9T/object/rider-12 \\\n -H 'Authorization: Bearer YOUR.ACCESS.TOKEN'\n"})}),"\n",(0,a.jsx)(t.p,{children:"This should return a JSON object with the object's data, e.g."}),"\n",(0,a.jsx)(t.pre,{children:(0,a.jsx)(t.code,{className:"language-js",children:'{\n "data": {\n "charge": 0.7\n },\n "label": "Delivery Rider 12",\n "location": {\n "accuracy": 0,\n "altitude": 0,\n "altitudeAccuracy": 0,\n "heading": 0,\n "latitude": 52.524,\n "longitude": 13.397567,\n "speed": 0,\n "time": "2024-02-20T08:47:45.260410438Z"\n }\n}\n'})}),"\n",(0,a.jsxs)(t.p,{children:["And that's it! You've successfully created, updated and read an object using Hivekit's HTTP API. You can now use this knowledge to manage other Hivekit entities like areas, instructions and tasks. If you have any questions, feel free to ask in the ",(0,a.jsx)(t.a,{href:"https://hivekit.io/contact/",children:"Hivekit Discord Chat or Contact us via email."}),"."]})]})}function d(e={}){const{wrapper:t}={...(0,i.a)(),...e.components};return t?(0,a.jsx)(t,{...e,children:(0,a.jsx)(l,{...e})}):l(e)}},4330:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/account-realm-access-management-8dd4bc4485f1c90c0d12b182b0e44ce0.png"},3264:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/account-realm-realm-id-6447380a97bdf780716fe5cb7556fedc.png"},9038:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/account-realm-token-25baacedc80bafb186b46ed6a5b4e17b.png"},7335:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/account-realm-096f2e27874527ccbfb20721474fb5d7.png"},5610:(e,t,n)=>{n.d(t,{Z:()=>a});const a=n.p+"assets/images/map-screenshot-d7b9d50b81cdd4d9810c0ba7caeb4071.png"},1151:(e,t,n)=>{n.d(t,{Z:()=>r,a:()=>o});var a=n(7294);const i={},s=a.createContext(i);function o(e){const t=a.useContext(s);return a.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function r(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:o(e.components),a.createElement(s.Provider,{value:t},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.