| Table of Contents |
|---|
...
Their various needs/goals (in order of priority)
“It’s something that we promised as part of an external project or tender”: Their org committed to connecting to our APIs and now they have to make it happen.
Researcher: “I want data that's in the same data model that comes from different institutions” and Europeana is the only place they can access that.
They have a startup idea and they want to use our APIs (e.g. Jama and his project Conzept)
Educators showing their class how to use linked open data without having to pay for an API key.
Other tools/services we have for them, and where they are:
APIs (currently on Pro), debug menu (currently in footer), etc
API documentation on Pro will go away and it will become the Confluence documentation;
Swagger consoles are a playground access to the API’s https://pro.europeana.eu/page/api-rest-console
Could have more prominence on the page because it’s a cool feature, where you can play with the APIs easily; Swagger console output is a much easier way to view the API and learn how our website uses it in the backend.
Either link to it from the page or embed it directly in the page. It’s more digestible bits of code that are much easier to use, and looks like this:
...
The needs of Jolan’s outreach efforts:
How does he currently promote our APIs and other developer tools/features?
They’re over marketed to ‘hey use our apis, use our data’ - so targeted physical outreach has been the most useful so far; conferences and hackathons where there’s a group of devs who are interested in the intersection of culture and development; this is more likely to get more people actually taking it up, following through, and making stuff.
The onboarding steps he follows:
gives a presentation,
prompts them to browse the website and get inspired by objects,
then he directs them to the debug page, and then they get a feel for what the data they're requesting looks like and how the requests work, get them inspired and the find something they want to use,
and he directs them to the documentation most specific for their use case
BIG LAUNCH OF HELP DOCUMENTATION IN FEB/MARCH SO IF THEY COINCIDE THAT WOULD BE NICE
How would he use a page like this, once everything is in one place at one URL?
This page would be between just surfing europeana.eu and then going into the deep documentation and active usage of our data; to help support this onboarding (above).
...
Richard, Lutz & Leonie, Feb 2024 (User feedback - as users of the Europeana API’s)
First section:
Show what's available in an easy to understand way, especially if the course isnt ready
...
Show only Record, Search, IIIF
Guided approach: How to use them together - Search, Record, IIIF as a core use case that makes sense chronologically
May add more eventually, but this is a strong start. Include "additional apis are available" somewhere lower in the page, just for completeness
"Most likely you'll want to use the Search api, this will help you find items...."
linking to documentation: Linking to these pages is a big jump, and an enormous amount of information to dump them onto
FAQ:
Show later, they're quite detailed..
Swagger console:
Weird to show this if the EDM is not even mentioned; but EDM is really complex and wouldn't make sense to show on this page
“I'm not too convinced about the usefulness of the swagger console at this level neither. Looking at it, it seems pretty complex and would require some knowledge of the data structure. Looking at these fields I don't even know what the callback field is for. And for new users, what profiles there are, how to know the collection and item IDs? Maybe instead we can come up with some really basic examples to really just get a user started and fetch something.”
Codepen:
Code samples that they can use, and how to use them
While that's quite a nifty example:
it doesn't work great on that demo page because the two pannels barely fit. So if it's something we'd include on the for developers page, we'd really need to make sure it has more room.
With using codepen, it's quite specific to the idea of using the API via a JS web app. Potentially we'd want something similar for a few different scenarios and languages. Or just a more generic "example" that just shows a HTTP request to the API, although then you're back to the swagger console if you want to allow users to modify that.
I know this is only an example, but I think we'd need to double check the actual URLSearchParams that are shown, as to how useful they are to new users and how we want to present them/the wording on those comments.
Inspiration section:
Ask Dasha if we could let him manage it via Contentful
How do we build Europeana section: devs think we should move/remove
Also on acknowledgements page - higher level, start with APIs, then JSON stuff, then these three things
Hugo, Feb 27 (Stakeholder feedback - as PO of APIs)
...