Stakeholder interviews: APIs product landing page

Owned by Julie Van Oyen
Last updated: Mar 06, 2024
8 min read

Jolan, Nov 24 (Stakeholder interview - APIs outreach)

  1. Brief overview of the users:

    1. How accurate is this user persona we’re currently using?

       

      1. Note that API work is often part of a person’s job (working as a developer at a CHI, or working at a startup, etc.)

      2. The ‘task’ listed above, 'Find ways to get help from the form (https://europeana.atlassian.net/wiki/pages/resumedraft.action?draftId=2395439141 ) and customer support’ is vague - they access help (support) primarily through a Google group and the API mailbox

      3. Note on ‘frustrations’ listed above:

        1. About documentation: Documentation will be addressed with version three of the API, with updated documentation that’s easier to read and simpler but still detailed enough.

        2. About not having enough examples: they do plan to have more examples in all their API docs

        3. About scrolling - this has been addressed in the confluence (https://europeana.atlassian.net/wiki/pages/createpage.action?spaceKey=EF&title=Europeana%20API%20Documentation ) with the embeddable tables in expand boxes.

        4. About range searches: Re-index last summer normalised the dates and solved this, and is now in their documentation.

      4. An additional frustration Jolan has heard consistently: The documentation has become quite outdated (for over a year now) - API team is aware of this but haven’t had time to update it yet, but people do comment via the feedback semi-regularly

      5. Note on ‘context of use’ listed above: the simplified version should be available, maybe the documentation wasn’t clear enough

    2. The above persona is very developer-centred; what about researchers?

      1. They differ a lot, there is a survey that shows the proportion of these users that are researchers (quite a significant portion): around 30%.

      2. His team created the harvesting and downloads page specifically for them. They don’t want to write code themselves, just to download in csv or another file format that they’d then put into their research software. They dont really even want an API key, they just want a link to google drive where they can download data sets directly;

      3. Creating a sub-persona for the researcher like this (data researcher, also a sub-persona of the researcher persona) may be useful;

      4. Harvesting and downloads page would likely be really helpful in a ‘For Researchers’ page (Alba’s); and then the dev page can have a link to that

    3. What percentage of our total users are in this group? See the user segments from 2019

      1. Idea: Julie to check forum to get an idea of numbers; also matomo

 

  1. Their various needs/goals (in order of priority)

    1. “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.

    2. 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.

    3. They have a startup idea and they want to use our APIs (e.g. Jama and his project Conzept)

    4. Educators showing their class how to use linked open data without having to pay for an API key.

  2. Other tools/services we have for them, and where they are:

    1. APIs (currently on Pro), debug menu (currently in footer), etc

      1. API documentation on Pro will go away and it will become the Confluence documentation;

      2. Swagger consoles are a playground access to the API’s https://pro.europeana.eu/page/api-rest-console

        1. 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.

        2. 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:

Instead of this:

 

  1. Help documentation (Confluence - anywhere else?)

    1. What kinds of things do these users need help with? (in order of priority)

      1. Syntax questions - they’ve made an error `nd they dont know why; The api is not working, which probably means they’ve malformed their requests

      2. How can they add to the api, how can we add to the database; we tell them they need to go thru the agg process, only for chi’s, sometimes theyre sent to henning if they are a chi; but personal requests are turned away

      3. What api is the one i should use for my use case? where to start, which api would give the data that they need

      4. check survey results slide deck: https://docs.google.com/presentation/d/1ytFgT4ylTfCTO1gji8s4O1r8wzEVablnUbYmQ5-7Nx8/edit#slide=id.g5ec88f338a_1_0 (check slide 5)

    2. Why on Confluence?

      1. With the expand boxes they can better embed the documentation tables directly in the articles;

      2. Easier and quicker for Jolan and the API team to update, rather than going through Pro team;

      3. Functionality is easier for specific needs of API documentation than pro;

      4. Confluence has really good user tracking - where they get stuck, specifically on which viewport of the page - very easy to see their whole granular user journey, page by page view by viewport.

      5. Finally, they want to connect it to EDM modelling and Europeana Publishing Framework articles (also on Confluence), cross-linking between them. This is easier if they’re all on the same platform - that’s a more consistent user experience.

    3. Will there also be Help pages on Europeana.eu (like what Paolo is doing for search)?

      1. Parts of it could fit on europeana.eu, which parts will be laid our in the platform strategy - for example, having one comprehensive FAQ on europeana.eu; or like Help for researchers could be on europeana.eu (simpler, less technical, less updated) whereas for devs it could stay on Confluence (more technical use-cases, where they need to follow complex & step-by-step instructions, and maybe even access the learning management system).

 

  1. Anything else re: users?

    1. It would be very useful to have a link on the item page to download the metadata file for this item, which also downloads the API response in there; in one button that’s easier to understand for the user (a small JASON file would be downloaded) - for Developers

    2. Also, a link download the full data set via CSV or something - for Data Researchers

    3. Doing a search or having a gallery and you get 200 items, being able to export that data set from a button or something in the UI - for Data Researchers

 

  1. The needs of Jolan’s outreach efforts:

    1. How does he currently promote our APIs and other developer tools/features?

      1. 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.

      2. The onboarding steps he follows:

        1. gives a presentation,

        2. prompts them to browse the website and get inspired by objects,

        3. 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,

        4. and he directs them to the documentation most specific for their use case

      3. BIG LAUNCH OF HELP DOCUMENTATION IN FEB/MARCH SO IF THEY COINCIDE THAT WOULD BE NICE

    2. How would he use a page like this, once everything is in one place at one URL?

      1. 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).

 

Review wireframe together.

Ask (answers in comments in file):

  1. Page content - is it complete? What is missing?

  2. Page hierarchy - most to least priority?

  3. Page visuals - potentially will get some customs icons and illustrations.

    1. What are some initial keywords/visual associations for APIs?

      1. API = sockets and plugs, electrical wiring, usb stick, fitting together, machinery, cogs, separate parts working in unison together, funnel/filter, little goblins/creatures going and gathering your data and moving it around, working behind the scenes

      2. API key = key? access cards, access

    2. For the other page concepts?

      1. CMS - filing cabinet

      2. Localisation - Multilingualism, speech bubbles, globe and flags

      3. Performance - speedometer going fast, speedy/fast

      4. Protection - shield? Likes the heart

 

 

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)

Onboarding improvements

Codepen section: This section will contain training resources; when the trainings are available, they should go here instead of this. If we implement this, it should be improved a bit (see Lutz's comments) and approved by Hugo.

That's relevant to the APIs brand also

Debug menu page and footer updates