console error when using .(dot) in parameter list

[meprateek1986]

My apiary documentation is on http://docs.prateek2.apiary.io/ There clicking on "project" api and "get projects by criteria" then I get below console error

Uncaught Error: Invalid Variable Name "members.userId" in "{?id,name,startdate,enddate,status,externalSystem,members.userId}"

We are using Apiary for our production purpose but right now as it is failing we are not able to publish the latest apis. Please help ASAP.

[honzajavorek]

@meprateek1986

The dot in your URI Template /project{?id,name,startdate,enddate,status,externalSystem,members.userId} indeed causes the problem. It shouldn't make the documentation throw errors into browser console though, that's for sure. We need to fix that.

The problem is that we implement URI Templates exactly according to the RFC 6570 standard. The standard doesn't allow you to have dot character in your template (you have it in the members.userId parameter), because it has a special meaning (see section 3.2.5).

UPDATE: following paragraph isn't true - please read comments below

The standard itself doesn't give us any way how to escape characters and we're still about to decide a strategy how to deal with the issue on parser level (https://github.com/apiaryio/snowcrash/issues/61), so the unfortunate outcome is that you need to avoid having dots in names of your parameters for now.

[honzajavorek]

@meprateek1986 I explored the https://github.com/apiaryio/snowcrash/issues/61 issue further and I see there should be a workaround. As stated in https://github.com/apiaryio/snowcrash/issues/58, it should be able to smuggle reserved characters into the URI Template by percent-encoding. That's the preferred way to escape. Sorry for turning you down at first!

As dot is unreserved character in normal URLs and as such it is not getting encoded by regular tools for percent-encoding (it's discouraged to encode unreserved characters) it's a bit tricky to get it's % variant, but this online tool helped me to get through the problem and the magic result is %2e.

If you write

/project{?id,name,startdate,enddate,status,externalSystem,members%2euserId}

in your blueprint, everything should work as intended. I just tried it out in sample Apiary project and it seemed to be displayed correctly, third column opened without a problem. Would this be a solution for you?

[meprateek1986]

It worked. Thanks Honza :)

[honzajavorek]

@meprateek1986 Awesome! I'm glad I could help!

[beetlerom]

We are using the . character in our query parameters in our APIs. While the workaround provided here works, it's a bit of a shame that after 2 years the RFC is still not correctly implemented.

Any chance to put this issue on the road-map anytime soon?

[marco-cdlv]

same issue it's being displayed as expected but when I execute the rest call to production option it throws me 400 error code due to the executed endpoint was changed from /api/v1/parent%2e.name to /api/v1/Parent%252eName.... why is changed from %2e to %252e?? @honzajavorek