Closed kakoni closed 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.
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¶m2=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.
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>
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.
+1 for both ways
@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.
@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>
@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.
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
Awesome work Petteri!
Wow! I call this lean and mean progress.
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
Petteri, could you release the code? There is an github repo for it;)
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.
The source code is now release. :)
Closing this, client exists.
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?