4 ms·

Yes, the API documentation is lacking especially with what we've gotten used to from Swagger markup and Stripe's API doc style. I have scoured for such an easy

Yes, the API documentation is lacking especially with what we've gotten used to from Swagger markup and Stripe's API doc style. I have scoured for such an easy breakdown and found none. As a result I actually just implemented a new, clear, client for LetsEncrypt and have been documenting as I go. It's made me think we should have a Swagger or API Blueprint of the spec on github that everyone can keep up to date. What do you think?

pfg 11y ago
Are you referring to the server-side API the client is communicating with, or the internal API the client exposes? The former is documented in the ACME specification[1], currently being worked on by the IETF. There are many low-level ACME libraries for basically every language[2], and a pretty decent guide on writing your own client as well[3]. [1]: https://ietf-wg-acme.github.io/acme/ https://ietf-wg-acme.github.io/acme/ [2]: https://github.com/letsencrypt/letsencrypt/wiki/Links#libraries https://github.com/letsencrypt/letsencrypt/wiki/Links#librar... [3]: https://github.com/alexpeattie/letsencrypt-fromscratch https://github.com/alexpeattie/letsencrypt-fromscratch
- simoncion 11y ago
  Just gonna mention that the IETF RFC viewer [0] puts you one click away from a diff between the current and previous rev of a document [1] which can be quite handy when implementing a WIP protocol. For non-draft documents, you also get a link to the RFC's Errata page at the top of the page. [0] https://tools.ietf.org/html/draft-ietf-acme-acme-02 https://tools.ietf.org/html/draft-ietf-acme-acme-02 [1] https://tools.ietf.org/rfcdiff?url2=draft-ietf-acme-acme-02.txt https://tools.ietf.org/rfcdiff?url2=draft-ietf-acme-acme-02....
- doublerebel 11y ago
  Thank you very much for these links. 3) is the closest to what I'm looking for, and really good! but is still an implementation and not a spec. 1) is fine for a spec for an internet committee who has to delve into every detail for standardization. But if a client can be written in 150 lines of code, there should be a much shorter version of the spec (only a couple pages) in a standard format. I should be able to easily write a client from a 3-page spec without looking at all the implementations. All due respect to the client authors, but only a few clients are good. Many are very poorly written, which I do not trust for security. I believe the cause is not having a clear, short, standard modern spec.
  - simoncion 11y ago
    > But if a client can be written in 150 lines of code, there should be a much shorter version of the spec (only a couple pages) in a standard format. I should be able to easily write a client from a 3-page spec without looking at all the implementations. Right, but even though the protocol is simple, there are pretty much always subtleties and potential ambiguities that need to be resolved by the spec so that one can write good implementations. > I believe the [problem] is not having a clear, short, standard modern spec. The IETF ACME draft spec is (like many IETF specs) clear, short, standard, and modern. The entire document is only 50 pages (fewer if you reduce the font size), and (from skimming the ToC) the last ~10 of those pages are largely optional material for someone who's just reading to implement the protocol. That document shouldn't take you more than an hour to read and digest. If you've never actually read an IETF spec they can be intimidating, but -if you're a programmer, network guy, or backend web dev- you really, REALLY owe it to yourself to learn how to read them: * Use the IETF's HTML RFC viewer rather than the plain text viewer. * Until you become familiar with the way IETF standards documents are written, don't skim! They're generally information-dense documents that do NOT repeat themselves. * Start from the beginning of the document and read through the end. * If the spec references another document, and then starts to talk about things from that document that you don't understand and can't figure out, go read the relevant parts of the referenced document. * If the spec starts presuming knowledge of things that you're sure it hasn't mentioned yet, backtrack a bit... you probably overlooked something. * The ASCII-art diagrams present in some specs aren't there for fun; they're important information. In regards to shorter documents, I'm not sure what you're looking for... just a listing of the HTTP conversations and their payloads?
    - nickpsecurity 11y ago
      Great write-up and advice! :)
    - doublerebel 11y ago
      My point is, the clients are generally pretty bad despite the IETF spec. Lots of edge cases ignored, poor security practices. I understand the intention but the effect is that the clients are just as opaque as the spec but often more incorrect. Who would try to launch a startup API for wide use without a Stripe-style spec these days? Thanks for the advice, but it's not that I don't understand how to read it, it's that I can tell other devs don't understand it despite the good intentions of the authors. Plenty of good clients are written for plenty of other tools, based on a much more straightforward call-and-response API spec. For example, the Hashicorp tools have a simple spec and proper clients in many languages.

pfg 11y ago

Are you referring to the server-side API the client is communicating with, or the internal API the client exposes? The former is documented in the ACME specification[1], currently being worked on by the IETF. There are many low-level ACME libraries for basically every language[2], and a pretty decent guide on writing your own client as well[3]. [1]: https://ietf-wg-acme.github.io/acme/ https://ietf-wg-acme.github.io/acme/ [2]: https://github.com/letsencrypt/letsencrypt/wiki/Links#libraries https://github.com/letsencrypt/letsencrypt/wiki/Links#librar... [3]: https://github.com/alexpeattie/letsencrypt-fromscratch https://github.com/alexpeattie/letsencrypt-fromscratch

simoncion 11y ago
Just gonna mention that the IETF RFC viewer [0] puts you one click away from a diff between the current and previous rev of a document [1] which can be quite handy when implementing a WIP protocol. For non-draft documents, you also get a link to the RFC's Errata page at the top of the page. [0] https://tools.ietf.org/html/draft-ietf-acme-acme-02 https://tools.ietf.org/html/draft-ietf-acme-acme-02 [1] https://tools.ietf.org/rfcdiff?url2=draft-ietf-acme-acme-02.txt https://tools.ietf.org/rfcdiff?url2=draft-ietf-acme-acme-02....
doublerebel 11y ago
Thank you very much for these links. 3) is the closest to what I'm looking for, and really good! but is still an implementation and not a spec. 1) is fine for a spec for an internet committee who has to delve into every detail for standardization. But if a client can be written in 150 lines of code, there should be a much shorter version of the spec (only a couple pages) in a standard format. I should be able to easily write a client from a 3-page spec without looking at all the implementations. All due respect to the client authors, but only a few clients are good. Many are very poorly written, which I do not trust for security. I believe the cause is not having a clear, short, standard modern spec.
- simoncion 11y ago
  > But if a client can be written in 150 lines of code, there should be a much shorter version of the spec (only a couple pages) in a standard format. I should be able to easily write a client from a 3-page spec without looking at all the implementations. Right, but even though the protocol is simple, there are pretty much always subtleties and potential ambiguities that need to be resolved by the spec so that one can write good implementations. > I believe the [problem] is not having a clear, short, standard modern spec. The IETF ACME draft spec is (like many IETF specs) clear, short, standard, and modern. The entire document is only 50 pages (fewer if you reduce the font size), and (from skimming the ToC) the last ~10 of those pages are largely optional material for someone who's just reading to implement the protocol. That document shouldn't take you more than an hour to read and digest. If you've never actually read an IETF spec they can be intimidating, but -if you're a programmer, network guy, or backend web dev- you really, REALLY owe it to yourself to learn how to read them: * Use the IETF's HTML RFC viewer rather than the plain text viewer. * Until you become familiar with the way IETF standards documents are written, don't skim! They're generally information-dense documents that do NOT repeat themselves. * Start from the beginning of the document and read through the end. * If the spec references another document, and then starts to talk about things from that document that you don't understand and can't figure out, go read the relevant parts of the referenced document. * If the spec starts presuming knowledge of things that you're sure it hasn't mentioned yet, backtrack a bit... you probably overlooked something. * The ASCII-art diagrams present in some specs aren't there for fun; they're important information. In regards to shorter documents, I'm not sure what you're looking for... just a listing of the HTTP conversations and their payloads?
  - nickpsecurity 11y ago
    Great write-up and advice! :)
  - doublerebel 11y ago
    My point is, the clients are generally pretty bad despite the IETF spec. Lots of edge cases ignored, poor security practices. I understand the intention but the effect is that the clients are just as opaque as the spec but often more incorrect. Who would try to launch a startup API for wide use without a Stripe-style spec these days? Thanks for the advice, but it's not that I don't understand how to read it, it's that I can tell other devs don't understand it despite the good intentions of the authors. Plenty of good clients are written for plenty of other tools, based on a much more straightforward call-and-response API spec. For example, the Hashicorp tools have a simple spec and proper clients in many languages.