Registrant portal API documentation

[maciej-szlosarczyk]

Contains new documentation for Registrant-centered API from #902. Open for discussion. Contact update will be actually implemented in #849.

[vohmar]

for registry lock the applied statuses need revision. I suggest applying only clientUpdateProhibited and clientDeleteProhibited. Different question is should we lock down the contacts as well - that would possibly require creating new objects or verifying that the objects are not associated with any other domain before we can do that, so for the first release I would leave it with domain object client side restrictions.

[maciej-szlosarczyk]

for registry lock the applied statuses need revision. I suggest applying only clientUpdateProhibited and clientDeleteProhibited.

I took the statuses from https://www.icann.org/resources/pages/epp-status-codes-2014-06-16-en, used all that had a mention of Registry Lock in the table. I'll update it to only include the ones you pointed out.

Different question is should we lock down the contacts as well - that would possibly require creating new objects or verifying that the objects are not associated with any other domain before we can do that, so for the first release I would leave it with domain object client side restrictions.

I wouldn't do that just yet, since as you pointed out there are some things to iron out. A related question is: What is the use case for the fact that contacts should be linkable with multiple (or none) domains? It would make this functionality (and other related ones) a lot easier if each contact object could be attached to exactly one domain.

[vohmar]

good doc, lets add clientTransferProhibited to the registry lock status list

[artur-intech]

why not just issuer?

[maciej-szlosarczyk]

Good thought. However, as I'm looking at it, I think it should be dropped completely as we are not accepting any other CAs than SK.

If needed later for usage with Belgian ID cards, we can restore this parameter as an optional one.

Thoughts?

[artur-intech]

Good idea! +1 for removing it, since it's kinda hardcoded.

[vohmar]

I am sorry but lets change up the statuses again. The problem is that even though in our case the current set of statuses is correct this would not serve its purpose when registrar side status editing is enabled - statuses with client prefix can be set and removed by registrar in that case. So to make the registry lock work as it supposed to in that case as well we should follow the icann document you referenced above and set serverUpdateProhibited, serverTransferProhibited and serverDeleteProhibited statuses instead.

[artur-intech]

Is there any reason why we need to send JSON request? I think it's much simpler to use it this way

curl https://api.example.com/v1/contacts -d first_name="John -d last_name=Doe

rather than creating JavaScript.

P.S. Applies to the entire API, not only to the line I commented.

[maciej-szlosarczyk]

It works both ways, either POST params or a JSON data structure (with properly set Content-Type header). However, as the main target for the API is to programatically integrate a portal, not serve one-off curl requests, I decided to document it with that in mind.

[artur-intech]

Why we need to support both request types? (application/json and application/x-www-form-urlencoded)

[maciej-szlosarczyk]

We don't need to and we do not support both explicitly. It works out-of-the-box unless you specify the following constraint in routes:

namespace :api, constraints: lambda { |req| req.format == :json }

I don't see a reason to introduce it, though.