A couple of API change suggestions

[nrusch]

I wanted to mention a couple of API design choices that I found odd to see if there was specific reasoning behind them, and see if it might be possible to change them in the future.

1. Task.TaskId is a string, rather than an int as one would expect. This also affects things like SlaveInfo.SlaveCurrentTaskIds.
2. Job.JobStatus, Task.TaskStatus, and SlaveInfo.SlaveState are all strings, rather than enum values or meaningful constants. This also affects things like SlaveInfo.SlaveCurrentTaskStatus.

Also, a number of types and enums are not documented at all, including ScriptDependency, AssetDependency, JobDependency (I think this exists…), StubLevel, SlaveScheduling mode, AutoJobCleanupType, etc.

[rrussell]

1. We use strings for the IDs because strings are used for the IDs for the other objects (jobs, slaves, etc). We went this way for consistency.
2. Enums don’t translate between .NET and Python, so you only see integers on the python side. That’s why they’re strings in the API.

Thanks for pointing out those missing docs. We’ll log it as an issue and get that fixed.

Cheers,
Ryan

[rrussell]

I should mention that the enums aren’t documented because the API uses strings.

[nrusch]

Thanks Ryan, I guess the first once makes sense. For the second one, I understand that it’s not automatic, but I think it would be nice to have some named constants (on a pseudo-enum type, for instance), as it helps during development to A) know what possible values something could have, and B) to avoid typos.