search

SIDN / ietf-epp-restful-transport

RESTful transport for EPP
Other
3 stars 4 forks source link

epp+xml translation to epp+json #28

Closed axeltomasson closed 6 months ago

axeltomasson commented 7 months ago

The document currently says "MUST support other content-types e.g.: application/epp+json" and to stop every implementation creating their own content-type: application/myTLD+json.

Will it be documented how the xml should be translated to json? That of course has the drawback of being more tied to the xml structure but behind the scenes the code can still validate against the xsd. Or just lots of data examples along side the xml examples with the freedom of implementing all new response json structure? Like other implementations currently in prod have done?

For example our proof of concept implementation (PHP) currently translates the xml automatically to mostly human readable json using some simple rules.

C: DELETE /v1/messages/29520 HTTP/2
C: Accept: application/json

S: content-type: application/json
S:
S:
S: {
S:     "response": {
S:         "result": {
S:             "code": "1000",
S:             "content": {
S:                 "msg": {
S:                     "lang": "en",
S:                     "content": "Command completed successfully"
S:                 }
S:             }
S:         },
S:         "msgQ": {
S:             "count": "1",
S:             "id": "29539",
S:             "content": {
S:                 "qDate": "2023-12-06T13:21:38+00:00",
S:                 "msg": {
S:                     "lang": "en",
S:                     "content": "Domain created"
S:                 }
S:             }
S:         },
S:         "resData": {
S:             "domain:panData": {
S:                 "domain:name": {
S:                     "paResult": "true",
S:                     "content": "example.com"
S:                 },
S:                 "domain:paTRID": {
S:                     "clTRID": "client-liejfleijfleijfeef",
S:                     "svTRID": "server-ifjelifjelifjflief"
S:                 },
S:                 "domain:paDate": "2023-12-06T13:21:38+00:00"
S:             }
S:         },
S:         "trID": {
S:             "clTRID": "client-fd87df87df998fd7fdf",
S:             "svTRID": "server-liejfliejfliejflefe"
S:         }
S:     },
S:     "ns": {
S:         "domain": "urn:ietf:params:xml:ns:domain-1.0"
S:     }
S: }
mwullink commented 7 months ago

it would be better if the json format and the rules for converting XML to JSON are in a separate document?

There are a lot of existing XML objects and extensions available already. Having rules for how to convert XML to JSON and not just stick with some examples would be something i prefer. Otherwise there might quickly exist a lot of incompatible implementations?

axeltomasson commented 7 months ago

it would be better if the json format and the rules for converting XML to JSON are in a separate document?

I don't know if separate document makes any difference since it would need to exist from day one? Pretty sure our resellers that have reached out to us wanting a more modern API wanted a JSON REST API. Some are not very fond of XML nor long lived TLS connections.

There are a lot of existing XML objects and extensions available already. Having rules for how to convert XML to JSON and not just stick with some examples would be something i prefer. Otherwise there might quickly exist a lot of incompatible implementations?

Yeah I agree I think rules (or code) how to convert are better then examples. Although we would always document examples outwards for our implementation to help resellers get up and running.

mwullink commented 7 months ago

I don't know if separate document makes any difference since it would need to exist from day one? Pretty sure our resellers that have reached out to us wanting a more modern API wanted a JSON REST API. Some are not very fond of XML nor long lived TLS connections.

agree, it would be nice to have the json format available at the same time as the api is ready. but it is better to decouple the representation formats and rules from the actual api. similar as how the EPP RFCs use different documents for describing objects suchs as domains,hosts and contacts

this way we can more easily add additional formats later, e.g. YAML without having to modify this api document.

Yeah I agree I think rules (or code) how to convert are better then examples. Although we would always document examples outwards for our implementation to help resellers get up and running.

I will create a new repository for a 2nd draft document describing the format rules for JSON. we can also add json examples in this new document

mwullink commented 7 months ago

i create a new repository for a document about howto add support for JSON. see: https://github.com/SIDN/ietf-epp-restful-json

would you like to become a co-author?

axeltomasson commented 7 months ago

We are looking into running the xsd's from the main rfc's through jgexml to get a json schema that can be used in an openapi spec. Maybe it will be usable with minor manual changes?

mwullink commented 6 months ago

working on simple rules for transforming xml to json in repo below. having a json schema would be nice

for questions and contributions, please see this repo: https://github.com/SIDN/ietf-epp-restful-json

closing this issue now.