search

educloudalliance / xroad-rest-gateway

Unmaintained repository. Development moved to
https://github.com/vrk-kpa/REST-adapter-service
European Union Public License 1.1
20 stars 11 forks source link

Calling service using Rest client #7

Closed kakoni closed 9 years ago

kakoni commented 9 years ago

In restful world you identify service using URL (example http://api.service.fi/users) but in security server/proxy world that wouldnt be the case I presume?

So the vision is to use something like http://localproxy (indicating the url of security server rest proxy) and then using X-XRd-Service http header to indicate what service you are calling?

andreskytt commented 9 years ago

Hi,

The idea, AFAIK, is to translate between the two. You'd have a url like

https://gw.finland.fi/org_name/svc_name be translated to a call to service "svc_name" at organization "org_name". How to pass parameters is still open. We could agree a canonical way of going from name-value pairs (and json) to xml (a.b!c=x to ) or have the caller compile full xml input and pass that. IMHO we should do both: the first drives neat service design and is good for simple services while the latter is good for legacy and complex requests.

Yours, Andres

On Friday, January 2, 2015, Karri Niemelä notifications@github.com wrote:

In restful world you identify service using URL (example http://api.service.fi/users) but in security server/proxy world that wouldnt be the case I presume?

So the vision is to use something like http://localproxy (indicating the url of security server rest proxy) and then using X-XRd-Service http header to indicate what service you are calling?

— Reply to this email directly or view it on GitHub https://github.com/educloudalliance/xroad-rest-gateway/issues/7.

petkivim commented 9 years ago

I agree with Andres, both ways are needed. Simple name-value pairs are enough for simple requests that have only URL parameters and no message body. All the GET requests fall into this category. For example:

[GET] http://api.service.fi/users/jdoe?param1=value1&param2=value2
<request>
  <resourceId>jdoe</resourceId>
  <param1>value1</param1>
  <param2>value2</param2>
</request>

Requests with message body should be converted to XML or message body could be transmitted as a SOAP attachment (no conversion is needed). I think that our primary goal should be XML conversion, even if the usage of SOAP attachments would be more straightforward. However, there are several cons regarding attachments, e.g. lack of schema definition; attachments are not signed and timestamped by v6 security server.

kakoni commented 9 years ago

So, using x-road service protocol example here as a basis (Chapter 7.1.6 calling data service). I would call this service in well restish manner as; [GET] https://gw.finland.fi/land-cadastre/land-cadastre.cuAddres.v1?province=0037&localGovernment=0784&cuOfficialName=cross%20road%20square*&cuMax=100 With following http-headers X-XRd-consumer: 10239452 X-XRd-producer: land-cadastre (_note, is this really needed?) X-XRd-userId: EE30101010007 X-XRd-id: 3aed1ae3813eb7fbed9396fda70ca1215d3f3fe1 X-XRd-service: land-cadastre.cuAddres.v1(_note, is this really needed?)

Correct?

And as a response I would get. Well, some xml perhaps, everything thats found under response?

<item>
 <cadastralUnit>012:345:67</cadastralUnit>
 <cuLocation>Cross Rode Square 1A</cuLocation>
 <province>0037</province>
 <localGovernment>0784</localGovernment>
 <registered>1999-09-19T19:09:10</registered>
 <purpose>001</purpose>
 </item>
 <item>
 <cadastralUnit>012:345:68</cadastralUnit>
 <cuLocation>Cross Rode Square 1B</cuLocation>
 <province>0037</province>
 <localGovernment>0784</localGovernment>
 <registered>1999-09-19T19:09:10</registered>
 <purpose>001</purpose>
</item>
margusf commented 9 years ago

In response to @petkivim : I think that the URI -> XML request translation idea is a good one. I have been thinking along the same lines.

However, there are several cons regarding attachments, e.g. lack of schema definition; attachments are not signed and timestamped by v6 security server.

Well, X-Road currently does not verify SOAP requests against WSDL also, so this aspect does not change when using attachments.

However, attachments are signed and time-stamped both in v5 and in v6.

kyyberi commented 9 years ago

+1 for both ways

petkivim commented 9 years ago

@margusf, thanks for clearing out how attachments are handled in v6. I've been under the impression that they're not signed, time-stamped or logged in the secure log. This eliminates 2/3 of the cons I mentioned.

I've implemented a simple solution that handles URI -> XML request translations (only HTTP GET currently), and new URIs can be added through configuration without changes to the source code. I'll upload it here in the next days. It still needs lot of improvement and it's for service providers only, but it's something concrete to begin with.

petkivim commented 9 years ago

@kakoni, your example uses v5 message headers, but basically it's correct. Here's an example how it would look like with v6 headers:

[GET] https://consumer.gateway.fi/?province=0037&localGovernment=0784&cuOfficialName=cross%20road%20square*&cuMax=100

HTTP headers:

X-XRd-Client: FI_PILOT.GOV.10239452
X-XRd-Service: FI_PILOT.GOV.land-cadastre.Subsystem.cuAddress.v1
X-XRd-Id: 3aed1ae3813eb7fbed9396fda70ca1215d3f3fe1
X-XRd-UserId: EE30101010007

Both X-XRd-Client and X-XRd-Service headers are needed as they identify the sender and the receiver of the message. In theory, X-XRd-Client header could be omitted from the request if the client identifier is defined in the gateway's configuration. If there are multiple clients accessing the same gateway instance, mapping identifiers to clients could be done by using IPs.

Consumer gateway converts the request to a SOAP message and sends it to the security server of the service consumer:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:id="http://x-road.eu/xsd/identifiers" xmlns:sdsb="http://x-road.eu/xsd/sdsb.xsd">
    <SOAP-ENV:Header>
        <sdsb:client id:objectType="MEMBER">
            <id:sdsbInstance>FI_PILOT</id:sdsbInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>10239452</id:memberCode>
        </sdsb:client>
        <sdsb:service id:objectType="SERVICE">
            <id:sdsbInstance>FI_PILOT</id:sdsbInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>land-cadastre</id:memberCode>
            <id:subsystemCode>Subsystem</id:subsystemCode>
            <id:serviceCode>cuAddress</id:serviceCode>
            <id:serviceVersion>v1</id:serviceVersion>
        </sdsb:service>
        <sdsb:userId>EE30101010007</sdsb:userId>
        <sdsb:id>3aed1ae3813eb7fbed9396fda70ca1215d3f3fe1</sdsb:id>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <ns:cuAddress xmlns:ns="http://land-cadastre.ee/">
            <ns:request>
                <ns:province>0037</ns:province>
                <ns:localGovernment>0784</ns:localGovernment>
                <ns:cuOfficialName>cross road square*</ns:cuOfficialName>
                <ns:cuMax>100</ns:cuMax>
            </ns:request>
        </ns:cuAddress>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

And this is how the SOAP response would look like. REST gateway returns everything inside response element to the information system that initiated the process.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:id="http://x-road.eu/xsd/identifiers" xmlns:sdsb="http://x-road.eu/xsd/sdsb.xsd">
    <SOAP-ENV:Header>
        <sdsb:client id:objectType="MEMBER">
            <id:sdsbInstance>FI_PILOT</id:sdsbInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>10239452</id:memberCode>
        </sdsb:client>
        <sdsb:service id:objectType="SERVICE">
            <id:sdsbInstance>FI_PILOT</id:sdsbInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>land-cadastre</id:memberCode>
            <id:subsystemCode>Subsystem</id:subsystemCode>
            <id:serviceCode>cuAddress</id:serviceCode>
            <id:serviceVersion>v1</id:serviceVersion>
        </sdsb:service>
        <sdsb:userId>EE30101010007</sdsb:userId>
        <sdsb:id>3aed1ae3813eb7fbed9396fda70ca1215d3f3fe1</sdsb:id>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <ns:cuAddressResponse xmlns:ns="http://land-cadastre.ee/">
            <ns:request>
                <ns:province>0037</ns:province>
                <ns:localGovernment>0784</ns:localGovernment>
                <ns:cuOfficialName>cross road square*</ns:cuOfficialName>
                <ns:cuMax>100</ns:cuMax>
            </ns:request>
            <ns:response>
                <ns:item>
                    <ns:cadastralUnit>012:345:67</ns:cadastralUnit>
                    <ns:cuLocation>Cross Rode Square 1A</ns:cuLocation>
                    <ns:province>0037</ns:province>
                    <ns:localGovernment>0784</ns:localGovernment>
                    <ns:registered>1999-09-19T19:09:10</ns:registered>
                    <ns:purpose>001</ns:purpose>
                </ns:item>
                <ns:item>
                    <ns:cadastralUnit>012:345:68</ns:cadastralUnit>
                    <ns:cuLocation>Cross Rode Square 1B</ns:cuLocation>
                    <ns:province>0037</ns:province>
                    <ns:localGovernment>0784</ns:localGovernment>
                    <ns:registered>1999-09-19T19:09:10</ns:registered>
                    <ns:purpose>001</ns:purpose>
                </ns:item>
            </ns:response>
        </ns:cuAddressResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
margusf commented 9 years ago

@petkivim :

@margusf, thanks for clearing out how attachments are handled in v6. I've been under the impression that they're not signed, time-stamped or logged in the secure log. This eliminates 2/3 of the cons I mentioned.

Well, the attachments are signed and time-stamped, but they are not logged by the security server (because they can make the log grow too fast). The decision whether to log attachments is left to the application (it is possible that the attachments do not contain anything important). If the application logs attachments, then they can be used as part of signature verification process.

petkivim commented 9 years ago

I've uploaded the very first version of the REST Gateway component that is for service providers only: it handles XML request -> URI translations (only HTTP GET currently).

https://github.com/educloudalliance/xroad-rest-gateway/releases/tag/v0.0.1

kakoni commented 9 years ago

Awesome work Petteri!

kyyberi commented 9 years ago

Wow! I call this lean and mean progress.

petkivim commented 9 years ago

The second version of REST Gateway is out now! Check out the release info:

https://github.com/educloudalliance/xroad-rest-gateway/releases/tag/v0.0.2

kakoni commented 9 years ago

Petteri, could you release the code? There is an github repo for it;)

petkivim commented 9 years ago

Yes, that's my plan, but I just haven't got time to do it yet. Currently the code is a part of a bigger project and it needs to be extracted from there first. Once that's done, I'll release it here. :) It's next on my to do list.

petkivim commented 9 years ago

The source code is now release. :)

kakoni commented 9 years ago

Closing this, client exists.