New Developer Portal Thoughts and Questions after testing it out

Not applicable

I like Drupal and I know that having it be part of the Apigee Developer portal provides a lot of powerful features and high degree of customizability. Unfortunately there are some areas where for us the Drupal based developer portal falls short:

* Slow performance / page loads when the user is logged in
* Smartdocs doesn't support oauth2 client credentials grant type
* Smartdocs information is not as helpful as swagger-ui
* Smartdocs doesn't allow you to provide sample code
* Applying our own theme to Drupal required some extra work due to the smartdocs module
* Having to check for updates to Drupal, testing things and managing Drupal (our api team is small)

I finally got a bit of time to test and play with the new developer portal. Here are some of my impressions and questions:

* Being able to use markdown to edit pages is great. We use github, so this feels being at home
* There is some degree of customizability since we can specify css for the portal. We can also add html or js to include at the bottom of every page
* Instead of having a single developer portal (like with the old Drupal approach), you can have many developer portals. I could see this being useful if you want to target multiple portals to different audiences
* Being able to just focus on the content, api products and Swagger is nice

Some questions / unknowns based on my testing:

  1. I didn't see a place where I could edit the 404 pages. I assume this feature is not available yet?
  2. Is it possible to add google analytics? I guess we could add a piece of js code to the footer of every page, but this seems like something that should be a built-in feature.
  3. Is it possible to interact with the developer portal using a git repo? One of the nice features of github wiki / pages is that you can interact with markdown locally and just push commits / updates.
  4. Are there any reports for the portal regarding the number of not-found pages or problems that people run into? This is something that Drupal provides and can help figure out problems in the site or with old / stale links.
  5. When I edit a page it automatically saves the text even if I don't publish it. There doesn't seem to be an intuitive way to undo changes.
  6. The markdown editor doesn't allow us to specify code blocks with code highlighting
  7. Can we setup an rss feed to our blog (which is external)?
  8. I didn't see a way where we could version the html changes to the theme. I guess we would have to manually keep track of our changes in a revision control system.
  9. The portal has smtp settings. I didn't see a contact form or something else that would make use of these settings.
  10. One of main downsides for us is the limited login functionality that was already mentioned in a separate community post by @jaskarangump
  11. With this new developer portal UI, there are now three different approaches for API documentation / interacting with developers: 1) the old api console, 2) Drupal developer portal and 3) new experience portal.

I know that the new developer portal is still not ready to be used as a replacement for the old Drupal architecture. I am impressed by the new interface, how responsive it is and how it it is clean, intuitive for the developer and registered keys page.

To be honest the new developer portal interface gives me hope that the Apigee developer portal GUI is getting closer to what I see that out there from companies that are doing a really good job with their developer portals. One of the open source projects that I liked regarding api docs is slate: https://github.com/lord/slate . It would be great if the new developer portal includes some of the features that slate provides such as:

* making it easier to include sample code
* integrating markdown changes with a git repo
* search
* making it easier to document APIs that don't always fit into Apigee proxies or that external to the organization

Is there a suggested topic tag for questions regarding the new developer portal?

1 5 556
5 REPLIES 5

Jose,

  1. Correct, we've been discussing the right way to provide a way to edit a 404 page, but it hasn't landed yet.
  2. The best way to add Google Analytics today is (as you guessed) to use the custom script feature. That will include it on every page. In the future we may consider a tighter integration.
  3. Good question about not-found and error reports. For now, I'd recommend instrumenting with Google Analytics and seeing the error reports and the previous page paths. This is an area we'll consider more as the portals mature.
  4. Agree that autosaving can be confusing as it is currently. We're working on page draft and publishing flow improvements now.
  5. Syntax highlighting would definitely help. How do you feel about adding the language name after the initial backticks, like ```javascript ? What languages would you need?
  6. I'm not sure what you're asking with regards to an RSS feed to your external blog… can you give a bit more detail?
  7. Saving versions of your CSS theme would help, as would versions of pages. We're considering both on the roadmap.
  8. SMTP settings are for the emails generated by your portal, for instance the account creation email. We're working on better controls for this.
  9. I feel your pain! We know username/password is important and is one of the bigger stories on our horizon. Since a system like that generally also needs an email verification flow, we started with that part so people could use the new portals sooner.
  10. Reconciling our various API documentation tools is another important story on our roadmap.

The new portals are still very new, but they are promising! For some customers, we already have enough features to satisfy their use cases—it's our highest priority to knock down any issues that are keeping others from putting them into production. Your feedback helps us prioritize the right stories, so thank you for giving it.

Hi Marsh,

Replies to your comments below:

5. Syntax highlighting would definitely help. How do you feel about adding the language name after the initial backticks, like ```javascript ? What languages would you need?

I was assuming I would be able to specify the language 🙂 . I think using backticks makes sense since that's what we're used to with github. As far as languages the main ones for us would be: javascript, java, python, ruby and php.

6. I'm not sure what you're asking with regards to an RSS feed to your external blog… can you give a bit more detail?

I was referring to being able to display a list of recent blog entries by specifying an rss feed. I guess I could do this via javascript. I have just come to expect sites to be able to parse an rss feed and display links to blog posts.

8. SMTP settings are for the emails generated by your portal, for instance the account creation email. We're working on better controls for this.

Thanks for the explanation. I wouldn't have guessed this. I can see some business requirements being strict about email settings for emails being sent by the developer portal.

Thanks for the response. I can see the benefit of getting started with the smallest set of use cases needed by some clients so that they can help with the testing and flushing out of the initial portal. Adding features over time is understandable if there is a public roadmap or transparency over features. For example, the old Drupal developer portal had some shortcomings, but after many months of the initial release it still was missing important features such as better support for swagger and trying out oauth2 based APIs with different grant types. Are there plans to make some of the upcoming enhancements visible to people in the community? It takes time to plan work so knowing ahead of time when a needed or blocking feature will be implemented is helpful rather than waiting for an announcement of a feature and then having to schedule things.

You may have discovered you can fence code blocks with backticks today, they just aren't getting syntax highlighting.

Your other clarifications helped, thank you. As a rule, we don't generally make roadmaps public (software has a way of messing with your "plans"), though we do try to be as transparent as we can when people ask specific questions.

Hi @Marsh Gardiner I am not seeing tryout operation for the api in the portal. This feature comes with swagger UI. I am not sure why it is not available in the new portal although it is built on top of swagger UI.

Thanks,

Krish

We removed the try-it functionality until we can properly pass in the logged in user's application credentials and negotiate the product entitlements. This is a story we plan to work on this summer (at least as far as we can foresee).