1"use strict";(globalThis.webpackChunkregardsoss_github_io=globalThis.webpackChunkregardsoss_github_io||[]).push([[5197],{81844(e,t,i){i.r(t),i.d(t,{assets:()=>a,contentTitle:()=>c,default:()=>h,frontMatter:()=>r,metadata:()=>n,toc:()=>d});const n=JSON.parse('{"id":"development/concepts/concepts-rest-api","title":"Microservices REST API","description":"All REGARDS microservices provide a REST API.","source":"@site/versioned_docs/version-2.2.0/development/concepts/05-rest-api.md","sourceDirName":"development/concepts","slug":"/development/concepts/rest-api/","permalink":"/docs/2.2.0/development/concepts/rest-api/","draft":false,"unlisted":false,"editUrl":"https://github.com/RegardsOss/RegardsOss.github.io/edit/master/versioned_docs/version-2.2.0/development/concepts/05-rest-api.md","tags":[],"version":"2.2.0","sidebarPosition":5,"frontMatter":{"id":"concepts-rest-api","title":"Microservices REST API","sidebar_label":"REST API","slug":"/development/concepts/rest-api/"},"sidebar":"dev","previous":{"title":"Multitenant","permalink":"/docs/2.2.0/development/concepts/multitenant/"},"next":{"title":"AMQP API","permalink":"/docs/2.2.0/development/concepts/amqp-api/"}}');var s=i(74848),o=i(28453);const r={id:"concepts-rest-api",title:"Microservices REST API",sidebar_label:"REST API",slug:"/development/concepts/rest-api/"},c=void 0,a={},d=[{value:"API documentation",id:"api-documentation",level:2},{value:"Authentification",id:"authentification",level:2},{value:"How to access REST API endpoints",id:"how-to-access-rest-api-endpoints",level:2},{value:"Access from outside",id:"access-from-outside",level:3},{value:"Access microservices directly",id:"access-microservices-directly",level:3}];function l(e){const t={a:"a",admonition:"admonition",br:"br",code:"code",em:"em",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsxs)(t.p,{children:["All REGARDS microservices provide a ",(0,s.jsx)(t.strong,{children:"REST API"}),"."]}),"\n",(0,s.jsx)(t.h2,{id:"api-documentation",children:"API documentation"}),"\n",(0,s.jsx)(t.p,{children:"On each REGARDS microservice, the documentation provides :"}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"API specifications"})," generated with ",(0,s.jsx)(t.a,{href:"https://swagger.io/",children:"Swagger"}),". For\nexemple, ",(0,s.jsx)(t.a,{href:"/docs/2.2.0/development/backend/services/fem/guides/rest/api",children:"here is the FEM microservice API specification"})]}),"\n",(0,s.jsxs)(t.li,{children:["Guides for main interfaces with detailed exemple of requests and responses to help you to interact with REGARDS\nendpoints. For\nexemple, ",(0,s.jsx)(t.a,{href:"../backend/services/fem/guides/rest/create-product",children:"here is the FEM guide to create a product"})]}),"\n"]}),"\n",(0,s.jsx)(t.h2,{id:"authentification",children:"Authentification"}),"\n",(0,s.jsx)(t.p,{children:"There is 2 ways to authenticate your request:"}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsxs)(t.li,{children:["By providing a Json Web Token (JWT). To do so, you must first authenticate through an ",(0,s.jsx)(t.strong,{children:"authentication service\nprovider"})," known by Regards. By default, Regards provides its own authentication service provider with Oauth2\nprotocol ",(0,s.jsx)(t.strong,{children:"rs-authentication"}),". Once you have successfully authenticated and retrieved an authentication token,\nyou can use it against the ",(0,s.jsx)(t.strong,{children:"gateway"})," microservice (or any ",(0,s.jsx)(t.em,{children:"reverse proxy"})," in front of the gateway) which will\nverify its validity and allow the request to reach its destination inside the REGARDS microservices using a hidden,\ninternal REGARDS token."]}),"\n"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:"curl https://<public host>:<public port>/<microservice>/api/v1/<endpoint> -H 'Authorization: bearer <sso token>'\n"})}),"\n",(0,s.jsx)(t.admonition,{type:"info",children:(0,s.jsxs)(t.p,{children:["See ",(0,s.jsx)(t.a,{href:"/docs/2.2.0/development/backend/services/authentication/api-guides/retrieve-token-oauth2/",children:"Authentication Guide"})," to learn how to retrieve a\ntoken from Regards authentication service ",(0,s.jsx)(t.strong,{children:"rs-authentication"}),".",(0,s.jsx)(t.br,{}),"\n","To learn more about additional authentication systems, see ",(0,s.jsx)(t.a,{href:"/docs/2.2.0/development/backend/services/authentication/contributor-guides/plugins/",children:"authentication plugins"}),"."]})}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsxs)(t.li,{children:["For public endpoints access (no authentication needed), you have to provide the REGARDS project in the request thanks to the parameter ",(0,s.jsx)(t.code,{children:"scope"})," to perform a request with no registered user."]}),"\n"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:"curl https://<public host>:<public port>/<microservice>/api/v1/<endpoint>?scope=<project>\n"})}),"\n",(0,s.jsx)(t.p,{children:"or"}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:"curl https://<public host>:<public port>/<microservice>/api/v1/<endpoint> -H 'scope: <project>'\n"})}),"\n",(0,s.jsx)(t.h2,{id:"how-to-access-rest-api-endpoints",children:"How to access REST API endpoints"}),"\n",(0,s.jsx)(t.h3,{id:"access-from-outside",children:"Access from outside"}),"\n",(0,s.jsxs)(t.p,{children:["To access endpoints from ",(0,s.jsx)(t.code,{children:"outside"})," the microservice installation server, you need to use the ",(0,s.jsx)(t.code,{children:"gateway"})," microservice (or\nany ",(0,s.jsx)(t.em,{children:"reverse proxy"})," in front of the gateway). To do so, use the following access point:"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:"curl https://<public host>:<public port>/<microservice>/api/v1/<endpoint>\n"})}),"\n",(0,s.jsx)(t.h3,{id:"access-microservices-directly",children:"Access microservices directly"}),"\n",(0,s.jsxs)(t.p,{children:["You can access each REGARDS API endpoint thanks to a ",(0,s.jsx)(t.code,{children:"Curl"})," request."]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:"curl http://<server name>:<microservice port>/<endpoint> -H 'Authorization: bearer <token>'\n"})}),"\n",(0,s.jsx)(t.admonition,{type:"note",children:(0,s.jsxs)(t.p,{children:["As you can notice, you do not need to prefix the endpoint with ",(0,s.jsx)(t.code,{children:"/<microservice>/api/v1/"})," if you access to the\nmicroservices directly"]})})]})}function h(e={}){const{wrapper:t}={...(0,o.R)(),...e.components};return t?(0,s.jsx)(t,{...e,children:(0,s.jsx)(l,{...e})}):l(e)}},28453(e,t,i){i.d(t,{R:()=>r,x:()=>c});var n=i(96540);const s={},o=n.createContext(s);function r(e){const t=n.useContext(o);return n.useMemo(function(){return"function"==typeof e?e(t):{...t,...e}},[t,e])}function c(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:r(e.components),n.createElement(o.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.