none
REST endpoint - best practices RRS feed

  • Question

  • Hello all,

    the question is related to expose a BizTalk orchestration as a REST web service .

    Short description :

    The Server is Biztalk 2013 R2 .

    The request is :

      <ns0:RestTestReq xmlns:ns0="http://RestTestProj.RestTestReq">
      <val>val_0</val> 
      <name>name_0</name> 
      <surname>surname_0</surname> 
      </ns0:RestTestReq>

    The response is :

      <ns0:RestTestRes xmlns:ns0="http://RestTestProj.RestTestRes">
      <val>val_0</val> 
      <name>name_0</name> 
      <surname>surname_0</surname> 
      </ns0:RestTestRes>

    For response , I'm copying the values from the request , in the orchestration .  The req-res logical port has the operation name "ResourceOp"

    I'm exposing the orchestration as a WCF-WebHttp  web service . On the service side I have the settings :

    Uri : /RestTestProj/Service1.svc

    <BtsHttpUrlMapping>
    <Operation Name='ResourceOp' Url='ResourceOp' />
    </BtsHttpUrlMapping>

    Receive pipeline :

    Custome pipeline that has "JSON decoder" component in Decode stage and "XML dissasembler" in Dissasemble stare (with the RestTestReq(my request) in the Document schemas collection)

    On the runtime of the pipeline I configured the "JSON Decoder" with :

    RootNode : RestTestReq

    RootNodeNamespace : http://RestTestProj.RestTestReq

    On send pipeline :

    Custom pipeline that has "JSON encoder" component on Encode stage . The outbound HTTP Headers on the Messages tab has the value :  "Content-Type: application/json"

    What I'm sending :

    To the endpoint : http://localhost

    Resource : /RestTestProj/Service1.svc/ResourceOp

    Method type : POST 

    Message sent (application/json):

    {
    "val": "String",
    "name": "String",
    "surname": "String"
    }

    What I'm receiving :

    {"RestTestRes": {
       "val": "STRING",
       "name": "STRING",
       "surname": "STRING"
    }}

    Questions :

    1) This is the desired implementation from the REST client point of view (sending the "body" of the message to a resource url where the body is wrapped with root name and namespace and transformed in xml ) ?

    An alternative will be to create a pipeline that will accept the Json message with root and namespace( as below) - but since I never worked with REST web services I don't know what are the best practices here :

    {

    "RestTestReq": {

      "@xmlns" : "http://RestTestProj.RestTestReq",

        "val": "STRING",
       "name": "STRING",
       "surname": "STRING"
       }

    }

    2)  I'm have the same orchestration exposed as a Soap WCF Req-res service . When something goes wrong with the orchestration , instead of providing a response back ,  I'm creating a typed fault message (RestTestFault) , that goes to the client on the fault soap channel .

    How this fault should be provided in case of the REST web service ? (A RestTestFault Json encoded , a soap fault with RestTestFault Json encoded  ??? ) . Again , I don't know what a REST client will expect in case of a typed fault

    Thanks  

    Thursday, June 15, 2017 3:21 PM

Answers

  • Hi Cezar

    1) Ideally you should not have namespaces in JSON payloads, so the below is preferred-

    {"RestTestRes": {
       "val": "STRING",
       "name": "STRING",
       "surname": "STRING"
    }}

    2) You can describe a JSON schema something like {"errorMessage":"String"} to return back any error message you want to send back. Also, you should set the correct HTTP response code like 500 on the outbound message using the OutboundHttpStatusCode property.


    Thanks Arindam

    • Marked as answer by CezarBotezatu Monday, June 19, 2017 8:02 AM
    Saturday, June 17, 2017 2:56 AM
    Moderator

All replies

  • Hi Cezar

    1) Ideally you should not have namespaces in JSON payloads, so the below is preferred-

    {"RestTestRes": {
       "val": "STRING",
       "name": "STRING",
       "surname": "STRING"
    }}

    2) You can describe a JSON schema something like {"errorMessage":"String"} to return back any error message you want to send back. Also, you should set the correct HTTP response code like 500 on the outbound message using the OutboundHttpStatusCode property.


    Thanks Arindam

    • Marked as answer by CezarBotezatu Monday, June 19, 2017 8:02 AM
    Saturday, June 17, 2017 2:56 AM
    Moderator
  • Thank you , Roy
    Monday, June 19, 2017 8:03 AM