Upcoming API changes
Hello everyone,
Some of you may know me already, but for those who don’t, let me briefly introduce myself.
I’m Mauro, senior backend engineer and a long-term Torn player (I’ve been playing this game for more than 10 years). I’m excited to announce that I will be working on and managing Torn’s API from this point onwards.
I look forward to working closely with everyone here to make Torn’s API more robust, standardized and better documented.
In the upcoming months, plan is to…
* Freeze v1 completely (except for any critical issues, exploits or if serious optimizations are needed)
* Work on v2 and refactor some of the codebase
* Standardize v2 to follow up the same standard on naming conventions, types, etc.
* Fix various bugs
* Introduce OpenAPI specification (now available here: https://www.torn.com/swagger/index.html#/)
* Enhance existing features
* Add new features
* Optimize some of the more heavy requests
* Publicly release v2 once it is in a meaningful state
If you have any suggestions, improvements, criticism or any (constructive) feedback at all - I’m more than happy to hear it!
Also, If you suspect any kind of abuse or think any part of the API might be abused, don’t hesitate to let me know.
Please note that once v2 is released, it will be still be unstable and there will be breaking changes from time to time. I will try to communicate such changes upfront, but I can’t promise anything at this moment.
Thank you,
Mauro
--
List of recent API changes:
20/11/2024
- Refactored 'faction' -> 'chain' in API v2
- Refactored 'faction' -> 'chains' in API v2
- Refactored 'faction' -> 'chainreport' in API v2
14/11/2024
- Added 'timestamp' endpoint to every section in Swagger
- Updated generic endpoints to have proper response instead of "any"
11/11/2024
- Added 'lookup' endpoint to every section in Swagger
- Fixed Swagger path parameter "categoryIds" in 'forum' -> 'threads' selection
08/11/2024
- Refactored all Swagger endpoints and removed query parameters from path
- Updated all auto-generated links to use the new service format
- Added '_metadata' field to various selections
- Improved 'user' -> 'races' to look into log tables as well
- Fixed incorrect swagger schema for 'user' -> 'races' & 'user' -> 'enlistedcars'
- Added "Stable" and "Unstable" Swagger tags
- Added generic endpoints for every section
04/11/2024
- Added 'rarity' field to 'user' -> 'itemmarket' & 'market' -> 'itemmarket' in API v2
- Added additional bonus filters to 'market' -> 'itemmarket'in API v2
- Fixed missing item information for some items in 'market' -> 'itemmarket' in API v2
- Changed 'torn' -> 'itemstats' to return 0 for "owner_id" field if item was never used or is being sold anonymously on item market
- Fixed 'user' -> 'hof' returning incorrect rank values for some players
29/10/2024
- Updated service to allow selections be requested as path variables
25/10/2024
- Added 'user' -> 'itemmarket' in API v2
- Added 'market' -> 'itemmarket' in API v2
14/10/2024
- Refactored 'faction' -> 'attacks' in API v2
- Refactored 'faction' -> 'attacksfull' in API v2
08/10/2024
- Added new selection 'faction' -> 'news' in API v2
01/10/2024
- Added new selection 'faction' -> 'wars' in API v2
- Refactored 'faction' -> 'basic' in API v2
25/09/2024
- Added 1 hour "global" cache to 'user' -> 'networth' in API v1
- Added cache timestamp to 'user' -> 'networth' in API v1
24/09/2024
- Added new selection 'user' -> 'bounties' in API v2
- Added new selection 'torn' -> 'bounties' in API v2
- Added new selection 'user' -> 'jobranks' in API v2
16/09/2024
- Updated 'torn' -> 'logcategories' in API v2
- Updated 'torn' -> 'logtypes' in API v2 (now accepts category id as input parameter)
09/09/2024
- Added Scamming data to 'miscellaneous' field to 'user' -> 'crimes' in API v2
- Added 'uniques' field to 'user' -> 'crimes' in API v2
04/09/2024
- Added 'is_revivable' field to 'faction' -> 'members' in API v2
03/09/2024
- Added new selection 'faction' -> 'members' in API v2
29/08/2024
- Added new selection 'user' -> 'calendar' in API v2
27/08/2024
- Added new selection 'torn' -> 'hof' in API v2
- Added new selection 'torn' -> 'factionhof' in API v2
- Added new selection 'faction' -> 'hof' in API v2
- Added new selection 'user' -> 'hof' in API v2
- Added racing hof ranking to 'user' -> 'hof' in API v1
20/08/2024
- Added custom key builder to the API docs page
15/08/2024
- Added new selection 'user' -> 'forumposts' in API v2
- Added new selection 'user' -> 'forumthreads' in API v2
- Added new selection 'user' -> 'forumsubscribedthreads' in API v2
- Added new selection 'user' -> 'forumfeed' in API v2
- Added new selection 'user' -> 'forumfriends' in API v2
06/08/2024
- Added new selection 'forum' -> 'categories' in API v2
- Added new selection 'forum' -> 'threads' in API v2
- Added new selection 'forum' -> 'thread' in API v2
- Added new selection 'forum' -> 'posts' in API v2
30/07/24
- Added new selection 'racing' -> 'records; in API v2
- Added new selection 'user' -> 'races' in API v2
- Added new selection 'user' -> 'enlistedcars' in API v2
24/07/24
- Added new selection 'racing' -> 'cars; in API v2
- Added new selection 'racing' -> 'carupgrades' in API v2
- Added new selection 'racing' -> 'tracks' in API v2
- Added new selection 'racing' -> 'races' in API v2
- Added new selection 'racing' -> 'race' in API v2
- Removed global cache in API v1 'user' -> 'bazaar' selection when requesting data for your own bazaar with "Custom", "Limited" or "Full" access keys
23/07/24
- Added new selection 'torn' -> 'calendar' in API v2
18/07/24
- Added global 30-second cache on 'user' -> 'bazaar' in API v1
17/07/24
- Added new selection 'user' -> 'criminalrecord' in API v1 returning the content of API v1 'user' -> 'crimes' selection with a public key
16/07/24
- Added new selection 'torn' -> 'crimes' in API v2 returning info about crimes 2.0
- Added new selection 'torn' -> 'subcrimes' in API v2 returning info about available actions for specific crimes
- Added new selection 'user' -> 'crimes' in API v2 returning user statistics for a specific crime
- Changed 'user' -> 'crimes' selection to require a key with "minimal" access (previously "public")
28/06/24
- Changed 'tokenrefills' in the 'user' -> 'personalstats' selection to be a private statistic
- Changed 'traveltime' in the 'user' -> 'personalstats' selection to produce coarsely rounded time increments
12/06/24
- Fixed incorrect defender faction name appearing on raid reports on 'torn' > 'raidreport'
- Changed the pawn shop points value to 0 to reflect its removal on 'torn' -> 'pawnshop'
Hey everyone,
I have great news regarding 'user' -> 'personalstats' selection!
We've managed to create a completely new system in which we're storing latest daily stats to our DB instead of FIreStore. This means the API is no longer restricted with FireStore.
The 'user' -> 'personalstats' selection has now been recreated in API v2, with everything now available in Swagger as well.
That said, it will still be possible to get all stats at once (in API v2), but you'll need to pass "all" as "cat" query parameter.
There's also a "popular" category now, which returns the most popular stats. We'd very much prefer if you use that instead of "all", but we understand there might be a legitimate need to use "all" category, e.g. for various community competitions etc.
if you think more stats should be included there, just drop me a message, but I've already tried to include everything that many tools might need.
We certainly did not have any intentions to purposefully break tools, so I can only thank everyone for the feedback - as I said in the original announcement we're open to feedback on these changes.
Hopefully this solution works well for everyone.
P.S. Some of you may get a message from me sometime soon, so we can work together on optimizing your tools (in case your tools are making more the 1,000,000/requests daily).
Thanks.
Quick note regarding API v1 - I've switched it to use daily stats just like Personal Stats page now since it's no longer limited by the FireStore.
That said, you can also pass a new "cat=all" in API v1 as well, to get all stats at once.
I plan on further improving API v2 & Swagger to allow passing as many stats as needed, but that will only work for snapshot stats, not for historical stats.
Thanks!
Hey everyone,
Smol change for both API v1 & API v2 - it's now possible to pass any amount of "stat" values in both API v1 and API v2, unless requesting historical stats - these are still limited to 10 as they're being fetched from FireStore.
Historical stats are being fetched if there's "timestamp" parameter present.
I've also changed "stalemated" and "assisted" in "attacking" schema into "stalemate" and "assist".
Swagger docs are also updated.
Thanks!
Will inventory access be restored to v1 post-inventory migration, or will it only be available for v2?
I presume this would fall under the exceptions for V1 changes.
I know you're waiting on other teams before you can do anything, but any information on when we could expect that inventory selection returning? We get asked this regularly over at PDA and currently my answer is "shrug, I'm not sure"
edit forgot to mention - congrats! Looking forward to the future of torn's api 🎉
Welcome to the Torn dev team!
Looks like a great plan outlined.
Hello!
I suspect I may be preaching to the choir, but I think a properly documented and publicly published roadmap with bugs/issues tagged against key milestones, and a rigorous development process which includes community involvement, might alleviate any "breaking" of changes that you might come across.
We can handle unstable, as long as we know it ahead of time.
~ Rich
p.s. I'm an opinionated pain in the ass. I'll apologise in advance if it helps.
~ P
Support my suggestions: Faction API Keys
Congrats on the new position! Looking forward to updates and increased stability (fingers crossed!).
One feature that would be nice to have is some sort of Forum API - it would create more opportunities for community-run events, such as this one. Something like Poster name, ID, time posted, last edited, post content, likes, dislikes.
Now if you'll excuse me, i'm off to scrape 50+ pages of posts to get the user IDs for the event :D
Yes please, something like this would be awesome. Access to the updates column via api (feed/subs/friends) would be nice too.
Also wouldn't mind an ability to search the forums but I understand that wouldn't really mix well with the current style of the api.... a duck can dream though. Being able to get notifs for people mentioning my name would be sick
Welcome! Super excited to have a developer focused on API changes.
One thing I think I and almost every developer would love to see is some sort of OAUTH2!
Welcorme, and nice name! Very excited also to have an independent developer working on the API, and what the future of the API could look like.
A few useful things off the bat:
All the best.
It's hard to say right now. That really depends on at what stage will v2 be after the inventory migration.
If there will still be a long way to finish v2, I think it will be reasonable to restore inventory section on v1 until then (provided it won't be too much db heavy).
As to on when is this going to happen - I can't provide any information there unfortunately.
And thank you! :)
Am I the only one who hates the key value thing I see everywhere in the torn api?
Happy to see an open api documentation for the V2 version of the API. Code generation is just not a fun experience with the torn api, open api should fix that :)
Is V2 going to be able to tell me how many calls I have left? Should be somewhere in the response body !
One of the most important things in my opinion is to streamline the suggestion process for the API. Currently it's driven by someone making a B&I post, Ched responding with "live in production" and that's that (slightly exaggerated of course, but the point is still the same), even if we are talking about breaking changes.
Documentation and an OpenAPI spec would be great, as what we currently have for official documentation doesn't even qualify to be called documentation imo. I'm trying my best to maintain a third-party documentation project, but first-party is always better.
Thank you everyone - there are some solid suggestions and advices here!
I'm still getting familiar with the codebase, but setting up a public project board is also something Chedburn suggested I should probably do, so I'm definitely open to doing that. It will just take some time to structure everything and write everything down, but we'll get there.
@DeKleineKobini - you do have a point. I agree that the current way of how API changes were made wasn't the easiest for those using the API, but considering how many things Chedburn is managing and doing, I think it's great he even managed to update the API at all!
Better documentation and OpenAPI spec is definitely something I see as a priority and must have have in v2.
I'll also set up a separate thread here for suggestions soon.
@Stig - auction API is something I too asked about a month ago - https://www.torn.com/forums.php#/p=threadsf=19t=16392176b=0a=0start=0to=24644707 and it's definitely something I'll look into at some point, but it might have to wait until the inventory rebuild is completed.
@Omanpx & @Kwack - I'll have to find out what could be done about the forum API, but I wouldn't be too optimistic here, at least not right away. I'm also not saying no, but I'm just seeing many potential issues here, especially considering the amount of data that forums hold.
But, I do like the ideas and especially considering it could enhance community driven events like the one you mentioned I'll investigate!
Thanks!
You've probably heard this thousands of times, but an Auction House API would be amazing :D
:P
I think that the crimeHubApi data should also be accessible through the normal player api. (This is data regarding what projects you currently are working on, how your card skimmers are doing, etc.)
The ability to paginate through more than the latest 100 reports on the user report endpoint, would be greatly appreciated.
Creator of www.tornspy.com.
Congrats, splent!! I'm so excited for what the future holds reading your inital roadmap. Amazing news!
Congrats on the job, I'm excited to see a more stable and standardised API at some point!
![splent [2088243]](/images/honors/843/h.png)
![Flid [2594918]](/images/honors/1277/h.png)
![Kwack [2190604]](/images/honors/321/h.png)
![Kwack [2190604], made by KingABz [1564719]](https://i.imgur.com/xbw52DO.gif)
![Kwack [2190604], courtesy of Ultr4Vi0let [2887202]](https://i.imgur.com/0lBqAhY.png)
![Kwack [2190604]](https://i.imgur.com/FTJwi9d.gif)
![MightyGoober [812478]](/images/honors/704/h.png)
![pobk [3171827]](/images/honors/129/h.png)
![Omanpx [1906686]](/images/honors/131/h.png)
![Stig [2648238]](/images/honors/132/h.png)
![Prokrist [585251]](/images/honors/163/h.png)
![DeKleineKobini [2114440]](/images/honors/700/h.png)
![tiksan [2383326]](/images/honors/1118/h.png)
![TurtReynolds [2472641]](/images/honors/1130/h.png)
![Hemicopter [2780600]](/images/honors/1104/h.png)
![Neodork [3026725]](/images/honors/1064/h.png)
![Heartflower [2626587]](/images/honors/210/h.png)