[Archivesspace_Users_Group] Find by ID API call

Wed Dec 14 09:06:04 EST 2022

Alan,

I'm happy to help and glad it's working!

I share your sentiments and frustrations with the API documentation. When I was first starting out, I was pinging the listserv and other places/people for help trying to understand how it works. Some stuff, like including [] in your cURL request parameters or encoding special characters, are just not there. Regarding the lack of documentation surrounding ARKs, I hope to include your example in the API docs for others to use in the future. The examples listed for that find_by_id endpoint don't include the --url-encode as an option, so I may include that in a comment for people having trouble.

Also, I am thinking about hosting an API workshop for people looking to get started or figure out how to use it to help automate their workflows. This isn't confirmed or official in any way, but I am curious to see how many people want something like this to see if it's worth doing. So if you, or others, would be interested - let me or the ASpace team know.

Thanks,

Corey

From: archivesspace_users_group-bounces at lyralists.lyrasis.org <archivesspace_users_group-bounces at lyralists.lyrasis.org> On Behalf Of Alan Manifold
Sent: Tuesday, December 13, 2022 5:15 PM
To: Archivesspace Users Group <archivesspace_users_group at lyralists.lyrasis.org>
Subject: Re: [Archivesspace_Users_Group] Find by ID API call

[EXTERNAL SENDER - PROCEED CAUTIOUSLY]
Thanks, Corey,
This one finally worked for me, based on using the --data-urlencode option and seeing what it did, along with the URL that worked for you (which included the host but not the http:// part).

                http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?ark[]=ark%3A%2F9999%2F119460<http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?ark%5b%5d=ark%3A%2F9999%2F119460>

Embarrassingly, I was using POST instead of GET, which didn't help my testing of the other aspects of the find_by_id API.

I have to say that the answer here was not at all obvious. There was no indication in the doco that you would have to encode the ARK, although all ARKs will have a colon and slashes. Most of our component_id's also have slashes and that wasn't indicated for them, either. Perhaps it's obvious to everyone else, but I have no idea why we include the "[]" after "ark". I guess you can use multiple values or something, but there's no indication of how that is done. It's great to have the full doco for all the APIs, but most of it is pretty cryptic. A few examples of actually use of them would really go a long way. I guess the fact that not so many sites are using ARKs is part of the problem here.

In any case, thank you very much for your help. I'm on my way now and that's down to you.

Regards,
Alan

Alan Manifold | Library Systems & Digital Preservation Manager | Collection Development & Description
State Library Victoria | 328 Swanston Street | Melbourne VIC 3000
T +61 3 8664 7122 | amanifold at slv.vic.gov.au<mailto:amanifold at slv.vic.gov.au>
slv.vic.gov.au<http://slv.vic.gov.au>

 [slv]
[https://www.slv.vic.gov.au/sites/default/files/email_signature/signature.jpg?9]<https://www.slv.vic.gov.au/email_campaign>

From: archivesspace_users_group-bounces at lyralists.lyrasis.org<mailto:archivesspace_users_group-bounces at lyralists.lyrasis.org> <archivesspace_users_group-bounces at lyralists.lyrasis.org<mailto:archivesspace_users_group-bounces at lyralists.lyrasis.org>> On Behalf Of Corey Schmidt
Sent: Wednesday, 14 December 2022 8:27 AM
To: Archivesspace Users Group <archivesspace_users_group at lyralists.lyrasis.org<mailto:archivesspace_users_group at lyralists.lyrasis.org>>
Subject: Re: [Archivesspace_Users_Group] Find by ID API call

Hey Alan,

Big caveat first: we don't use ARKs where I work, so I'm flying a little blind here. I enabled ARKs on our testing space just to see if I could replicate your request. Here's what I tried and it returned the correct archival object:

curl -H "X-ArchivesSpace-Session: $SESSION" "https://our_api_url/repositories/2/find_by_id/archival_objects?ark[]=www.testarkurl.com/ark:/YLTAD111/51/37;resolve[]=archival_objects<https://our_api_url/repositories/2/find_by_id/archival_objects?ark%5b%5d=www.testarkurl.com/ark:/YLTAD111/51/37;resolve%5b%5d=archival_objects>"

I added an external ARK URL to the archival object and put www.testarkurl.com/ark:/YLTAD111/51/37<http://www.testarkurl.com/ark:/YLTAD111/51/37> in that field. Are you using something like this or trying to access internal ARKs? If it's internal, I don't have a way to test that, I'm afraid. Though it seems like the following requests are constructed properly:

http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?component_id[]=YLTAD111/51/37<http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?component_id%5b%5d=YLTAD111/51/37>
http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?ref_id[]=15a419a9464353be174f77bdc8f38874<http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?ref_id%5b%5d=15a419a9464353be174f77bdc8f38874>   (our ref_ids look something like this usually: "ref36_286", that looks like the container_id found in an EAD export)

If you're still getting a 404 error, I might also try using the "--url-encode" parameter to see if that helps. Dave Mayo at Harvard pointed me in this direction which works great for the find_by_id endpoint for resources. Using that would look something like:

curl -H "X-ArchivesSpace-Session: $SESSION" -G http://ourhost.com:8089/repositories/5/find_by_id/archival_objects --data-urlencode 'component_id[]=YLTAD111/51/37'

If you do find a solution, would you mind sharing it with the listserv or me? I wrote the API cURL and Python examples for that endpoint and I couldn't find anyone using ARKs to build an example from. Adding that would be the last piece of the puzzle for that documentation.

Hope this helps,

Corey
Corey Schmidt
Special Collections Libraries | Project Management Librarian/Archivist
Corey.Schmidt at uga.edu<mailto:Corey.Schmidt at uga.edu>
From: archivesspace_users_group-bounces at lyralists.lyrasis.org<mailto:archivesspace_users_group-bounces at lyralists.lyrasis.org> <archivesspace_users_group-bounces at lyralists.lyrasis.org<mailto:archivesspace_users_group-bounces at lyralists.lyrasis.org>> On Behalf Of Alan Manifold
Sent: Monday, December 12, 2022 10:50 PM
To: ArchivesSpace Users Group <archivesspace_users_group at lyralists.lyrasis.org<mailto:archivesspace_users_group at lyralists.lyrasis.org>>
Subject: [Archivesspace_Users_Group] Find by ID API call

[EXTERNAL SENDER - PROCEED CAUTIOUSLY]
Hi ArchivesSpace folks,
I've been trying to get the find_by_id API call to work and haven't had any luck. What I really want is to be able to find archival objects by ARK, but I tried the other types of IDs to see if they would work and tell me something useful. But I can't get any of them to work. We're on version 3.2.0. I have a program that establishes a connection and gets a session ID, then sends off the API call. When the same program sends this search API, it works:

http://ourhost.com:8089/search?q=component_id:"YLTAD111/51/37<http://ourhost.com:8089/search?q=component_id:%22YLTAD111/51/37>" OR component_id:"YLTAD111/51/38" OR component_id:"YLTAD111/51/39"&page=1

Here's what I have tried:

http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?ark=https://ourhost.com/ark:/9999/119460
http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?ark=ark:/9999/119460
http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?ark=119460
http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?ark[]=ark:/9999/119460<http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?ark%5b%5d=ark:/9999/119460>
http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?ark[]=119460<http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?ark%5b%5d=119460>
http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?component_id[]=YLTAD111/51/37<http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?component_id%5b%5d=YLTAD111/51/37>
http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?component_id[]=YLTAD111%2F51%2F37<http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?component_id%5b%5d=YLTAD111%2F51%2F37>
http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?component_id[]='YLTAD111%2F51%2F37<http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?component_id%5b%5d='YLTAD111%2F51%2F37>'
http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?component_id[]='YLTAD111<http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?component_id%5b%5d='YLTAD111>'
http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?component_id[]=YLTAD111<http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?component_id%5b%5d=YLTAD111>
http://ourhost.com:8089/repositories/3/find_by_id/archival_objects?component_id[]=YLTAD111<http://ourhost.com:8089/repositories/3/find_by_id/archival_objects?component_id%5b%5d=YLTAD111>
http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?component_id[]=YLTAD111;resolve[]=archival_objects<http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?component_id%5b%5d=YLTAD111;resolve%5b%5d=archival_objects>
http://ourhost.com:8089/repositories/3/find_by_id/archival_objects?component_id[]=MS%2015856;resolve[]=archival_objects<http://ourhost.com:8089/repositories/3/find_by_id/archival_objects?component_id%5b%5d=MS%2015856;resolve%5b%5d=archival_objects>
http://ourhost.com:8089/repositories/3/find_by_id/archival_objects?component_id[]=MS<http://ourhost.com:8089/repositories/3/find_by_id/archival_objects?component_id%5b%5d=MS> 15856;resolve[]=archival_objects
http://ourhost.com:8089/repositories/3/find_by_id/archival_objects?component_id[]=MS_15856;resolve[]=archival_objects<http://ourhost.com:8089/repositories/3/find_by_id/archival_objects?component_id%5b%5d=MS_15856;resolve%5b%5d=archival_objects>
http://ourhost.com:8089/repositories/3/find_by_id/archival_objects?component_id[]=MS10840-1.1.1;resolve[]=archival_objects<http://ourhost.com:8089/repositories/3/find_by_id/archival_objects?component_id%5b%5d=MS10840-1.1.1;resolve%5b%5d=archival_objects>
http://ourhost.com:8089/repositories/3/find_by_id/archival_objects?component_id[]=MS10840-1.1.1;resolve[]=archival_objects<http://ourhost.com:8089/repositories/3/find_by_id/archival_objects?component_id%5b%5d=MS10840-1.1.1;resolve%5b%5d=archival_objects>
http://ourhost.com:8089/repositories/3/find_by_id/archival_objects?component_id[]=MS10840-1.1.1<http://ourhost.com:8089/repositories/3/find_by_id/archival_objects?component_id%5b%5d=MS10840-1.1.1>
http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?ref_id[]=15a419a9464353be174f77bdc8f38874<http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?ref_id%5b%5d=15a419a9464353be174f77bdc8f38874>
http://ourhost.com:8089/repositories/5/find_by_id/archival_objects?ref_id=15a419a9464353be174f77bdc8f38874

Every single call returned a 404 error. Can anyone tell me what I'm doing wrong? I'll feel stupid if it's obvious, but I'll still be thankful. Thanks so much!

Regards,
Alan

Alan Manifold | Library Systems & Digital Preservation Manager | Collection Development & Description
State Library Victoria | 328 Swanston Street | Melbourne VIC 3000
T +61 3 8664 7122 | amanifold at slv.vic.gov.au<mailto:amanifold at slv.vic.gov.au>
slv.vic.gov.au<http://slv.vic.gov.au>

 [slv]
[https://www.slv.vic.gov.au/sites/default/files/email_signature/signature.jpg?9]<https://www.slv.vic.gov.au/email_campaign>

This message and any attachment is intended only for the use of the Addressee and may contain information that is PRIVILEGED and CONFIDENTIAL. If you are not the intended recipient, you are hereby notified that any dissemination of this communication is strictly prohibited. If you have received this communication in error, please delete all copies of the message and its attachments and notify the sender immediately. Thank you.
This message and any attachment is intended only for the use of the Addressee and may contain information that is PRIVILEGED and CONFIDENTIAL. If you are not the intended recipient, you are hereby notified that any dissemination of this communication is strictly prohibited. If you have received this communication in error, please delete all copies of the message and its attachments and notify the sender immediately. Thank you.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lyralists.lyrasis.org/pipermail/archivesspace_users_group/attachments/20221214/c913ce30/attachment.html>