Upcoming API Changes for Industry
Posted: Wed Jun 18, 2014 3:14 pm
http://community.eveonline.com/news/dev ... -industry/
Another API-related dev blog in a matter of weeks. This is getting out of hand. I may have to stop writing them if this is the pace they are happening. For now however we need to have a quick talk about changes that are coming to the EVE API in the July Crius release.
Right now there are two endpoints from which you can get industry jobs from: corp/IndustryJobs and char/IndustryJobs. The information relating to industry jobs is changing pretty drastically in Crius and so something had to be done about these two endpoints. Given that the EVE API does not really support versioning we came up with two options:
1) Leave the current endpoints in place and just have them stop returning data. They would act as if you had no jobs, so the boiler plate data would be there but no rows. We would then add a new endpoint along the lines of char/newIndustryJobs (or my favourite suggestions char/stEVEJobs).
Pros: This does not break existing applications.
Cons: If you are a new API developer and want to get industry jobs and you see these endpoints it's pretty confusing. It's really confusing to get 0 data when you are expecting something.
2) The second option is to convert the existing endpoint and give third party developers as much time as possible to update their stuff. Doing this would require we get these endpoints live on the Singularity (Sisi) test server ASAP for testing.
Pros: Makes sense for future developers.
Cons: Risks breaking old applications that do not have proper error handling.
It's a tough choice but after asking the CSM, #eve-dev, others around the office, and just thinking about it for a bit, we have chosen to go with option 2. We will replace the existing IndustryJobs endpoints with new data and hope we don't anger many people. To that end the following API changes are live on Sisi right now:
Added corp/Facilities:
Listing all of a corporations facilities, including POS and Outpost
You need a corporation key and a character with director, CEO, or factory manager roles to view this endpoint.
This endpoint is cached for 1 hour.
Updated char/IndustryJobs and corp/IndustryJobs:
Conforms to the new data being returned for jobs within EVE.
To see the corp jobs you must be director, CEO, or have the factory manager role.
This endpoint will return all running jobs and is cached for 1 hour.
Added char/IndustryJobsHistory and corp/IndustryJobsHistory:
Will return the same kind of data as industryJobs but will include both running and completed jobs.
This is cached for 24 hours and as of now will include up to 1,000 rows.
We are working on a better way of controlling the amount of rows returned so expect that to change.
Same requirements for corp jobs as the IndustryJobs endpoint.
The above is all on Sisi right now so you guys can get testing and update your stuff. We will be listening to your feedback in the comments of this dev blog and we still have plenty of time before Crius goes live to change how we are doing this if that is deemed the correct course of action.
BONUS ROUND!
As an extra special bonus CCP Tuxford has added two new endpoints to public CREST on Sisi for industry related activities.
You can find them here: public-crest-sisi.testeveonline.com/industry/
Disclaimer
All of the above is on Sisi and still in active development. While we will try and keep you apprised of any changes, things may change before they are released to TQ.
That's all for now, just a quick heads up on things to be aware of.
CCP FoxFour
@regnerba
Another API-related dev blog in a matter of weeks. This is getting out of hand. I may have to stop writing them if this is the pace they are happening. For now however we need to have a quick talk about changes that are coming to the EVE API in the July Crius release.
Right now there are two endpoints from which you can get industry jobs from: corp/IndustryJobs and char/IndustryJobs. The information relating to industry jobs is changing pretty drastically in Crius and so something had to be done about these two endpoints. Given that the EVE API does not really support versioning we came up with two options:
1) Leave the current endpoints in place and just have them stop returning data. They would act as if you had no jobs, so the boiler plate data would be there but no rows. We would then add a new endpoint along the lines of char/newIndustryJobs (or my favourite suggestions char/stEVEJobs).
Pros: This does not break existing applications.
Cons: If you are a new API developer and want to get industry jobs and you see these endpoints it's pretty confusing. It's really confusing to get 0 data when you are expecting something.
2) The second option is to convert the existing endpoint and give third party developers as much time as possible to update their stuff. Doing this would require we get these endpoints live on the Singularity (Sisi) test server ASAP for testing.
Pros: Makes sense for future developers.
Cons: Risks breaking old applications that do not have proper error handling.
It's a tough choice but after asking the CSM, #eve-dev, others around the office, and just thinking about it for a bit, we have chosen to go with option 2. We will replace the existing IndustryJobs endpoints with new data and hope we don't anger many people. To that end the following API changes are live on Sisi right now:
Added corp/Facilities:
Listing all of a corporations facilities, including POS and Outpost
You need a corporation key and a character with director, CEO, or factory manager roles to view this endpoint.
This endpoint is cached for 1 hour.
Updated char/IndustryJobs and corp/IndustryJobs:
Conforms to the new data being returned for jobs within EVE.
To see the corp jobs you must be director, CEO, or have the factory manager role.
This endpoint will return all running jobs and is cached for 1 hour.
Added char/IndustryJobsHistory and corp/IndustryJobsHistory:
Will return the same kind of data as industryJobs but will include both running and completed jobs.
This is cached for 24 hours and as of now will include up to 1,000 rows.
We are working on a better way of controlling the amount of rows returned so expect that to change.
Same requirements for corp jobs as the IndustryJobs endpoint.
The above is all on Sisi right now so you guys can get testing and update your stuff. We will be listening to your feedback in the comments of this dev blog and we still have plenty of time before Crius goes live to change how we are doing this if that is deemed the correct course of action.
BONUS ROUND!
As an extra special bonus CCP Tuxford has added two new endpoints to public CREST on Sisi for industry related activities.
You can find them here: public-crest-sisi.testeveonline.com/industry/
Disclaimer
All of the above is on Sisi and still in active development. While we will try and keep you apprised of any changes, things may change before they are released to TQ.
That's all for now, just a quick heads up on things to be aware of.
CCP FoxFour
@regnerba