Missing API Documentation

The site refers you to the master draft of the specification, but the following seem to be missing from Let’s Encrypt’s implementation:

new-nonce New nonce
new-account New account
new-order New order

I assume that we get just get the nonce from the headers on each communication, but how do we create an account or an order?

Is there documentation somewhere specific to Let’s Encrypt’s implementation?

I think this will give you the best information, it links to the currently-implemented draft and lists divergences between that draft and Let’s Encrypt’s software (Boulder).

5 Likes

Hi @meccahost - Can you be more specific about where on the site we do this? I'd like to fix it to be clearer about the divergences with the current implementation like we do on the page about ACME protocol updates.

@jared.m is correct (Thanks!) - Boulder and the "V1" API evolved alongside the draft ACME protocol document. At the time of implementation none of the endpoints you mention existed :slight_smile: We document each as a divergence and you'll find that the "V2" API we intend to make available in addition to V1 in Feb will have the endpoints you are mentioning and considerably fewer protocol divergences for clients to respect.

Hope that helps!

The first place we went was Documentation and then Client and Large Provider Integration Guide; unfortunately, we did not find any details there. From there, we went to Getting Started and found that you were using the acme protocol, but the link on that page didn’t take us to the details of the protocol. From there we went to the FAQ and found a link to ACMEv2, which is how we got there – this was the first link we found that actually took us to a specification, so that’s what we assumed was being used.

I would say that as a developer, the first place we’re going to go is the integration guide, and unfortunately, we didn’t find details on integration there. Additionally, the Getting Started page is another place that one would probably check first; if not the integration guide, and the details were not found there either. I think that the FAQ is also another good place to have links to the actual specification that you’re using.

I have to say it was a frustrating experience for a seasoned developer that’s just trying to get to the API details and some example code, there was not much to be found. It’s a very complex protocol which definitely needs to be clearly documented with some more details showing example communications between the client and server.

The "How It Works" page has a hyperlink (Hyperlink - Wikipedia) underneath the text "ACME protocol" in its first sentence. The destination of that hyperlink currently is ietf-wg-acme/acme master preview

On that page, there are three hyperlinks to the actual protocol draft: a formatted and structured version of the current draft underneath the html hyperlink and also an unstructured one beneath the plain hyperlink.

By the way, the same hyperlink to the ACME protocol exists on the "Getting Started" page.

What "details of the protocol" were you unable to find on the protocol page?

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.