di-ms2-api.json

{"apiVersion":"2.4-SNAPSHOT","apis":[{"description":"publishConnectionChangeEvent","operations":[{"method":"POST","summary":"Publish an update of the gateway connection state","notes":"The API allows updating with the same value multiple times.","nickname":"publishConnectionChangeEvent","produces":["*/*"],"consumes":["application/json"],"parameters":[{"allowMultiple":false,"defaultValue":"","description":"connectionState","name":"body","paramType":"body","type":"ConnectionStateChangeEventJson","required":false}],"responseMessages":[{"code":200,"message":null,"responseModel":"ResultJson"},{"code":401,"message":"Operation not allowed","responseModel":"Void"},{"code":404,"message":"Unknown deviceId","responseModel":"Void"}],"deprecated":"false","type":"ResultJson"}],"path":"/deviceManagement/connectionState"},{"description":"getGateway","operations":[{"method":"GET","summary":"Get gateway attributes by the specified deviceId","notes":"All names are for display purposes only, not Business Keys or Ids. The structure allows multiple Business Units per Gateway because a gateway could connect Equipments from several Business Units.","nickname":"getGateway","produces":["*/*"],"consumes":["application/json"],"parameters":[{"allowMultiple":false,"defaultValue":"","description":"A unique identifier of a gateway","name":"deviceId","paramType":"path","type":"string","required":true}],"responseMessages":[{"code":200,"message":null,"responseModel":"GatewayJson"},{"code":401,"message":"Operation not allowed","responseModel":"Void"},{"code":404,"message":"Unknown deviceId","responseModel":"Void"}],"deprecated":"false","type":"GatewayJson"}],"path":"/deviceManagement/gateways/{deviceId}"},{"description":"invalidateCurrentOpenVPNCertificate","operations":[{"method":"DELETE","summary":"Invalidate current Gateway OpenVPN Certificate","notes":"This must fail unless there are currently 2 valid certificates (current and new). If the new current one is invalidated, the new one becomes the current one. The invalidated certificate will be added to the revocation list.TODO: Does this imply potentially a message to users?","nickname":"invalidateCurrentOpenVPNCertificate","produces":["*/*"],"consumes":["application/json"],"parameters":[{"allowMultiple":false,"defaultValue":"","description":"deviceId","name":"deviceId","paramType":"path","type":"string","required":true}],"responseMessages":[{"code":200,"message":null,"responseModel":"ResultJson"},{"code":400,"message":"If certificate not known, or only one certificate is valid.","responseModel":"Void"},{"code":401,"message":"Operation not allowed","responseModel":"Void"},{"code":404,"message":"Unknown deviceId","responseModel":"Void"}],"deprecated":"false","type":"ResultJson"}],"path":"/deviceManagement/gateways/{deviceId}/certificates/currentOpenVPNCertificate"},{"description":"invalidateCurrentProSystCertificate","operations":[{"method":"DELETE","summary":"Invalidate current Gateway ProSyst Certificate","notes":"This must fail unless there are currently 2 valid certificates (current and new). If the new current one is invalidated, the new one becomes the current one. The invalidated certificate will be added to the revocation list.TODO: Does this imply potentially a message to users. TODO: Do we even need to invalidate, or even to store this certificate?","nickname":"invalidateCurrentProSystCertificate","produces":["*/*"],"consumes":["application/json"],"parameters":[{"allowMultiple":false,"defaultValue":"","description":"deviceId","name":"deviceId","paramType":"path","type":"string","required":true}],"responseMessages":[{"code":200,"message":null,"responseModel":"ResultJson"},{"code":401,"message":"Operation not allowed","responseModel":"Void"},{"code":404,"message":"Unknown deviceId","responseModel":"Void"}],"deprecated":"false","type":"ResultJson"}],"path":"/deviceManagement/gateways/{deviceId}/certificates/currentProSystCertificate"},{"description":"invalidateNewOpenVPNCertificate","operations":[{"method":"DELETE","summary":"Invalidate new Gateway OpenVPN Certificate","notes":"This can be used in special situations if a new certificate was requested, but was then not deployed on gateway and will never be deployed on gateway.","nickname":"invalidateNewOpenVPNCertificate","produces":["*/*"],"consumes":["application/json"],"parameters":[{"allowMultiple":false,"defaultValue":"","description":"deviceId","name":"deviceId","paramType":"path","type":"string","required":true}],"responseMessages":[{"code":200,"message":null,"responseModel":"ResultJson"},{"code":401,"message":"Operation not allowed","responseModel":"Void"},{"code":404,"message":"Unknown deviceId","responseModel":"Void"}],"deprecated":"false","type":"ResultJson"}],"path":"/deviceManagement/gateways/{deviceId}/certificates/newOpenVPNCertificate"},{"description":"createNewOpenVPNCertificate","operations":[{"method":"POST","summary":"Request creation of new Gateway OpenVPN Certificate","notes":"This is only possible if there currently is only one certificate (the current one). After the call, the new certificate can be used immediately, but the current one will still remain the current one. The certificate expiry duration is defined in DI Backend. The current certificate will remain usable (not on revocation list) until explicitly invalidated.","nickname":"createNewOpenVPNCertificate","produces":["*/*"],"consumes":["application/json"],"parameters":[{"allowMultiple":false,"defaultValue":"","description":"createCertificateJson","name":"body","paramType":"body","type":"CreateCertificateJson","required":false}],"responseMessages":[{"code":200,"message":null,"responseModel":"CertificateJson"},{"code":400,"message":"If cipher suite name not known / allowed, if already 2 valid certificates exist","responseModel":"Void"},{"code":401,"message":"Operation not allowed","responseModel":"Void"},{"code":404,"message":"Unknown deviceId","responseModel":"Void"}],"deprecated":"false","type":"CertificateJson"}],"path":"/deviceManagement/gateways/{deviceId}/certificates/newOpenVPNCertificate"},{"description":"createNewProSystCertificate","operations":[{"method":"POST","summary":"Request creation of new Gateway ProSyst Certificate","notes":"This is only possible if there currently is only one (current) certificate.The new certificate can be used immediately, but the current one will still remain the current one. The current one will remain usable (not on revocation list) until explicitly invalidated.","nickname":"createNewProSystCertificate","produces":["*/*"],"consumes":["application/json"],"parameters":[{"allowMultiple":false,"defaultValue":"","description":"createCertificateJson","name":"body","paramType":"body","type":"CreateCertificateJson","required":false}],"responseMessages":[{"code":200,"message":null,"responseModel":"CertificateJson"},{"code":400,"message":"If cipher suite name not known / allowed, if already 2 valid certificates exist","responseModel":"Void"},{"code":401,"message":"Operation not allowed","responseModel":"Void"},{"code":404,"message":"Unknown deviceId","responseModel":"Void"}],"deprecated":"false","type":"CertificateJson"}],"path":"/deviceManagement/gateways/{deviceId}/certificates/newProSystCertificate"},{"description":"invalidateNewProSystCertificate","operations":[{"method":"DELETE","summary":"Invalidate new Gateway ProSyst Certificate","notes":"This can be used in special situations if a new certificate was requested, but was then not deployed on gateway and will never be deployed on gateway. TODO: Do we even need to invalidate, or even to store this certificate?","nickname":"invalidateNewProSystCertificate","produces":["*/*"],"consumes":["application/json"],"parameters":[{"allowMultiple":false,"defaultValue":"","description":"deviceId","name":"deviceId","paramType":"path","type":"string","required":true}],"responseMessages":[{"code":200,"message":null,"responseModel":"ResultJson"},{"code":401,"message":"Operation not allowed","responseModel":"Void"},{"code":404,"message":"Unknown deviceId","responseModel":"Void"}],"deprecated":"false","type":"ResultJson"}],"path":"/deviceManagement/gateways/{deviceId}/certificates/newProSystCertificate"},{"description":"getGatewayOpenVPNCertificate","operations":[{"method":"GET","summary":"Get current (and new) gateway OpenVPN Certificate in PEM Format","notes":"During a transition phase before the certificate expires, it is possible that two certificates are defined, the current one, and the one mPrm has requested to be put onto a gateway via USB.","nickname":"getGatewayOpenVPNCertificate","produces":["*/*"],"consumes":["application/json"],"parameters":[{"allowMultiple":false,"defaultValue":"","description":"A unique identifier of a gateway","name":"deviceId","paramType":"path","type":"string","required":true}],"responseMessages":[{"code":200,"message":null,"responseModel":"AllCertificatesJson"},{"code":401,"message":"Operation not allowed","responseModel":"Void"},{"code":404,"message":"Unknown deviceId","responseModel":"Void"}],"deprecated":"false","type":"AllCertificatesJson"}],"path":"/deviceManagement/gateways/{deviceId}/certificates/openVPNCertificates"},{"description":"getGatewayProSystCertificate","operations":[{"method":"GET","summary":"Get current (and new) gateway ProSyst Certificate in PEM Format","notes":"TODO: For ProSyst, only need a current certificate?","nickname":"getGatewayProSystCertificate","produces":["*/*"],"consumes":["application/json"],"parameters":[{"allowMultiple":false,"defaultValue":"","description":"A unique identifier of a gateway","name":"deviceId","paramType":"path","type":"string","required":true}],"responseMessages":[{"code":200,"message":null,"responseModel":"AllCertificatesJson"},{"code":401,"message":"Operation not allowed","responseModel":"Void"},{"code":404,"message":"Unknown deviceId","responseModel":"Void"}],"deprecated":"false","type":"AllCertificatesJson"}],"path":"/deviceManagement/gateways/{deviceId}/certificates/proSystCertificates"},{"description":"publishCertificateRenewalRequiredEvent","operations":[{"method":"POST","summary":"Request notification of user to put gateway online.","notes":"Request sending of user notification event that certificates must be renewed but cannot be renewed because gateway is offline.","nickname":"publishCertificateRenewalRequiredEvent","produces":["*/*"],"consumes":["application/json"],"parameters":[{"allowMultiple":false,"defaultValue":"","description":"deviceId","name":"body","paramType":"body","type":"string","required":false}],"responseMessages":[{"code":200,"message":null,"responseModel":"ResultJson"},{"code":401,"message":"Operation not allowed","responseModel":"Void"},{"code":404,"message":"Unknown deviceId","responseModel":"Void"}],"deprecated":"false","type":"ResultJson"}],"path":"/deviceManagement/gateways/{deviceId}/notifications/certificateRenewalRequired"},{"description":"publishCertificateRenewalSuccessEvent","operations":[{"method":"POST","summary":"Request sending of user notification event that certificates have been successfully updated.","notes":"TODO: if DI needs to remember if prior warning about unconnected gateway was sent, then invalidateCertificate call may be sufficient as trigger.","nickname":"publishCertificateRenewalSuccessEvent","produces":["*/*"],"consumes":["application/json"],"parameters":[{"allowMultiple":false,"defaultValue":"","description":"deviceId","name":"body","paramType":"body","type":"string","required":false}],"responseMessages":[{"code":200,"message":null,"responseModel":"ResultJson"},{"code":401,"message":"Operation not allowed","responseModel":"Void"},{"code":404,"message":"Unknown deviceId","responseModel":"Void"}],"deprecated":"false","type":"ResultJson"}],"path":"/deviceManagement/gateways/{deviceId}/notifications/certificateRenewalSuccessful"}],"basePath":"/api","consumes":["application/json"],"models":{"CertificateJson":{"description":"","id":"CertificateJson","properties":{"certificate":{"description":"The certificate that is assumed to be on the Gateway in PEM Format","required":true,"type":"string"},"certificatePrivateKey":{"description":"The private key generated for the certificate","required":true,"type":"string"}}},"AllCertificatesJson":{"description":"","id":"AllCertificatesJson","properties":{"currentCertificate":{"description":"The certificate that is assumed to be on the Gateway in PEM Format","required":true,"type":"CertificateJson"},"newCertificate":{"description":"The certificate that should be put onto the gateway next in PEM Format, if any.","required":false,"type":"CertificateJson"}}},"ResultJson":{"description":"","id":"ResultJson","properties":{"status":{"enum":["ok","error"],"description":"if ok, the other fields should be null. Else, the other fields may have additional information for debugging / display","required":true,"type":"string"},"message":{"description":"Generic field, may contain the cause in case of an error","required":false,"type":"string"},"translatedMessage":{"description":"Generic field, may contain the translation in case of an error or the translation key if no translation is present","required":false,"type":"string"},"info":{"description":"Generic field, may contain additional information in some cases of an error","required":false,"type":"object"}}},"ConnectionStateChangeEventJson":{"description":"","id":"ConnectionStateChangeEventJson","properties":{"deviceid":{"description":"A unique identifier of a gateway","required":true,"type":"string"},"isOnline":{"description":"Whether the status is online (=true) or not (=false)","required":true,"type":"boolean"}}},"CreateCertificateJson":{"description":"","id":"CreateCertificateJson","properties":{"deviceId":{"description":"A unique identifier of a gateway","required":true,"type":"string"},"cipherTypeName":{"description":"A name of the cipher suite as accepted by JSSE providers","required":true,"type":"string"}}},"GatewayJson":{"description":"","id":"GatewayJson","properties":{"deviceid":{"description":"A unique identifier of a gateway","required":true,"type":"string"},"gatewayName":{"description":"A display name for a gateway","required":true,"type":"string"},"locationName":{"description":"Name of the gateway location or null","required":true,"type":"string"},"isActive":{"description":"Whether the gateway is in operation (=true) or not (=false). For Lyconsyst Gateways, active is implied by whether the BU is a pseudo-BU at Lyconsyst or an end-customer BU.","required":true,"type":"boolean"},"businessUnitNames":{"description":"Name of business units that are related to the gateway. This is an arbitrarily ordered list of Business Units of the equipments attached to the gateway.","items":{"type":"string"},"required":true,"type":"array","uniqueItems":true}}}},"produces":["*/*"],"resourcePath":"/deviceManagement","swaggerVersion":"1.2"}