If you worked with VKontakte API before, or have an existing app using it, you will find Smithereen API very familiar. However, it’s not a straight drop-in replacement – both because VK and Smithereen operate under different constraints, and because VK has some tech debt that makes no sense to replicate in a built-from-scratch project. That said, in most cases, it should not be too complicated to adapt an existing VK app to work with Smithereen.
Here are the main differences:
- All booleans are real JSON booleans. In VK API, older “boolean” fields use 1/0 instead of true/false. This was done because historically, the API used to support returning its responses in XML, which has no notion of data types, and because gzip compression wasn’t ubiquitous, and this supposedly saved some bytes in large responses. In Smithereen, everything is true/false.
- All enums are human-readable strings. In VK API, many enumerable values, especially things like user profile fields, are magic numbers. Smithereen gets rid of that inscrutable nonsense.
- Most methods that take object IDs don’t require an owner ID. VK is a high-load, distributed system, with everything spread across tens of thousands of database, storage, and application servers. Those owner IDs are how an application server knows which database instance to query for the object you’re referring to. Smithereen is a monolith that only supports using a single database server, and so has no need for such things.
- Some object IDs are strings. IDs for photo albums, photos, private messages, comments, and board topics are, to prevent enumeration attacks.
- Posts, comments, and some profile and group fields support text formatting and are HTML. Just ActivityPub things. Your app is also expected to supply formatted text as Markdown or HTML when creating posts and comments or updating those profile fields.
- Deletion is permanent for everything except private messages. When deleting most objects, VK allows restoring them shortly after. The usual UX is that deletions happen immediately, without a confirmation, but the deleted object is replaced with a link or button to restore it (and most
*.deletemethods have a corresponding*.restore). Smithereen can’t do that because this can’t be done cleanly in a federated system – you either tell the network about the deletion immediately, or delay it by that period during which the object can be restored. Since the latter would feel awkward to users (“I deleted this, why is it still on that other server?!”), the former approach was chosen, making the replication of VK’s behavior impossible. - Errors affect the HTTP status code. VK API is endlessly ridiculed for returning
HTTP/1.1 200 OK ... {"error": {...}}. There isn’t really a convincing technical reason for such behavior other than “we made it this way in 2008, are terrified to break compatibility unless we get a promotion for it and too lazy to do a proper gradual migration to a new behavior, and besides, it’s not broken”, so Smithereen does the more RESTful thing with returning 4xx and 5xx codes for all error responses. - No support for stored procedures. The execute method is an extremely powerful tool, and Smithereen does provide it, with some enhancements compared to VK’s version. However, stored procedures, the canned pre-compiled
executes that on VK you edit in the app management UI, aren’t possible to implement in a decentralized system, as sticking them into theApplicationobjects that Smithereen uses for application metadata would be impractical to say the least. You will have to send your code over every time you need to run it. - id1 is not Pavel Durov. Sorry about that.