Some feedback on the /:job API endpoint

[richard-jones]

In the process of documenting, some oddities and inconsistencies which came up:

• There is an inconsistency between the form of an identifier in a job request, and the form of an identifier in a report about the job. Job request is:

{
    "Article title" : "[title of the article]",
    "DOI" : "[article DOI]",
    "PMCID" : "[Europe PMC identifier for the article (starting with 'PMC')]",
    "PMID" : "[PubMed identifier for the article]"
}

Info about a job is:

{
    "process": "[per-identifier process id]",
    "PMID": "[pubmed id]",
    "DOI": "[doi]",
    "pmcid": "[EuropePMC id]",
    "title": "[Article title]"
}

Note differences in capitalisation, and "Article title" becomes "title"

• What does "process" mean in the info about a job, when attached to an identifier record. Is this useful to the user?
• Capitalisation of keys is inconsistent in job info and responses in general. "PMCID" and "DOI" but "pmid" and "title"
• Job ids are referenced differently in different places. On create it is in the key "job", but everywhere else it is "_id" (_id is also used in a different context elsewhere)
• Why does the progress report also indicate the user's email address?
• In the final results, the keys "_id" and "process" are both present for each record, containing the same information.
• In the final results "pmid" and "PMID" are both present, as are "doi" and "DOI".

Propose for overall consistency to use lower case keys everywhere, which would fix most of the oddities.

[markmacgillivray]

Oddities are mostly due to Wellcome things. Originally I lowercased and used pmid, doi, pmcid, title. But this was not acceptable to Wellcome, so I had shifted various bits of formatting into specific functions that handle formatting depending on whether Wellcome user or not, but as there has been no use of the API by them (and no other testing of it done yet), I probably missed some things that are writing them in different forms within the JSON data. I can check, and agree lowercasing is my preferred option anyway, and "article title" gets reduced to "title".

"process" is the ID of the process that will get the answer for the identifiers provided. There is a process for every row / set of identifiers provided in the job list. The process ID can be used to look up the processes on the processes endpoint - although this can be very short lived, so may not be useful. Very often, possibly now always, it will be the same as the _id of the process. This info could probably just be removed from the results if you prefer - as mentioned, to date I don't actually have any provided requirements for the API, beyond what the UI needed it do and what I wanted it to do.

When you create a job you get back the ID of the job. Then you use that ID to get at the job later. The job is the ID of the job.

I think progress report includes user email because of old Wellcome requirements, when things had to be fiddled to allow them to use the system without logins. This is probably no longer necessary due to the way progress is notified to users having changed, but the email address is still in there. Can be removed if you prefer.