API things

[momijizukamori]

I kept meaning to write this up but kaberett's volunteer weekend was a good extra nudge, heh.


what is live
- To generate API keys (and delete them), go here - this can be found via Manage Accounts -> Mobile -> Advanced Options (which is at the bottom of the mobile tab)
- The JSON-formatted spec is here and doesn't require an API key to access - we don't have a more human-friendly version yet, though any client that can parse OpenAPI v3.0 specs can take that - Postman is the one I've tried.
- There are not many routes yet - we wanted to get the backend solid before adding stuff that had potential privacy/security risks if something in the backend was wrong
- To use the API key, you need to add an Authorization header to your HTTP request with the value 'Bearer [api key]'.



what is in progress
- I have a pile of routes mostly-written, in this branch. They probably need some light editing, as we moved from OpenAPI v2.0 to v3.0 after I wrote these, and we also hadn't implemented API keys yet. They also need LOTS AND LOTS of testing, oh god please, I'm so bad at QA.
- I wrote a quick'n'dirty primer to adding moar routes here on the wiki. Happy to answer additional questions on it!



what really needs to be done
- TESTING TESTING TESTING
- image-upload-by-API is near the top of the list of 'most wanted things I haven't written yet'
- I want to add a nice UI for the spec a la redoc but I'm not totally sold on that as a look and could use design input and inspiration
- We really need some intro/'API for beginners' text to go on said doc page, I am probably not the right person to write this because I Know Too Much
- It would be great to have a priv system for API keys (so that you could make a key that can read and not post, or vice versa). There are stubs in the API key files for this, but it needs UI and DB stuff as well as... filling out the stubs.
- 404s under /api should really return a JSON 404 message and not... the entire HTML output of the 404 page.

Comments

[kaberett]

\o/ THANK YOU. :D

[alexwlchan]

\o/

Thanks for the details!

Is there any way to test the API yet? I’d be happy to help write some of it, but I like having tests to support my work. (And if not, I could think about creating one next time I do Dreamwidth dev work.)

[siderea]

SO EXCITE!!!

[jducoeur]

Ooooo, neat!

[bcholmes]

Hm. I'm seeing some oddities w.r.t. character encoding. I have a couple of userpics that have "smart" single quotation marks in them, and they don't seem to be rendering properly.

JSON is supposed to be UTF-8 encoded, and the header I get back from the /users/{userid}/icons call is "Content-Type: application/json; charset=utf-8", but the content of the comments field sometimes has odd characters in it.

[nataraj]

Hi!

I want to write some perl script, that would do posting to dreamwidth, using it's API, but did not find not any ready-to-use perl module, not an API spec. As far as I get from this post some kind of API actually exist. Where should I start.

I guess while solving my task I can do some doc or code writing that would be useful to community, but I need to understand what actually exists, and what should be done.

Can somebody help me with that?

[nataraj]

Sorry for long pauses... But I have first questions/comments:

1. http://www.nataraj.hack.dreamwidth.net/api/v1/journals/nataraj/entries Will it really return ALL journal entries? If I do it for my (nataraj) journal. It will be really long list, that will take a lot of resources... I guess pagination is needed here for sure. It can't be put in production the way it is now.

2. http://www.nataraj.hack.dreamwidth.net/api/v1/journals/nataraj/entries/886

"body_raw" : "This is <b>Entry 3</b>",

I would expect here another attribute that will tell what is the formatting is used in raw text. Even if it is only html available for now, I guess is should be specified explicitly.

1. Can I turn on markdown posts beta on my dreamhack? How can I do it?

---

I guess it would be also good if you start showing me around in DW code. I guess if you show me key points in the code, I will be able to file merge request for issues like raw-content-type myself. But I am not insisting on this.