krz/devianter

 1// Package devianter is a client for DeviantArt's internal "_puppy" API, the
 2// JSON backend that deviantart.com's own web frontend calls.
 3//
 4// This is not the official, documented DeviantArt API. There is no application
 5// registration and no OAuth: the package authenticates the way a logged-out
 6// browser does, by fetching a guest session cookie and a CSRF token from the
 7// homepage. Everything reachable here is what an anonymous visitor can see.
 8// Because the endpoints are internal, DeviantArt can change or remove them
 9// without notice.
10//
11// # Usage
12//
13// Call [UpdateCSRF] once before anything else to establish the guest session.
14// Every other call depends on the cookie and token it stores, and will fail
15// until it has run:
16//
17//	if err := devianter.UpdateCSRF(); err != nil {
18//		log.Fatal(err)
19//	}
20//
21//	post, apiErr := devianter.GetDeviation("123456789", "someuser")
22//	if apiErr.Reason != "" {
23//		log.Fatal(apiErr.Error)
24//	}
25//	fmt.Println(post.Deviation.Title, post.IMG)
26//
27// The session does not refresh itself. A long-running program should call
28// [UpdateCSRF] again when calls start failing, since tokens expire.
29//
30// # Errors
31//
32// Most functions return an [Error] value rather than a Go error. It is a struct,
33// not an interface, so it is never nil; a call succeeded if Error.Reason is
34// empty. Functions that can also fail on their arguments before any request is
35// made (such as [PerformSearch] and [Group.Gallery]) return an ordinary error
36// alongside it for that case.
37//
38// # Rate limiting and blocking
39//
40// DeviantArt sits behind CloudFront, which blocks IP addresses that request too
41// aggressively. A blocked request surfaces as an [Error] whose Error field
42// mentions CloudFront/WAF. This package does no rate limiting, retrying, or
43// backoff of its own; a caller making bulk requests is expected to pace itself.
44// Set [UserAgent] to identify your client and [Timeout] to bound each request.
45package devianter