Slashdot Mirror

← Back to Stories (view on slashdot.org)

Ask Slashdot: Best API Management System?

Posted by Soulskill on from the notepad-and-lots-of-coffee dept.

An anonymous reader writes: I've landed a summer internship with a software firm that has a library of APIs available to current and potential customers. One of my team's tasks is to make recommendations on how to improve the developer portal, which not only provides a testing sandbox and documentation, but is also a source of sales leads for the company's business units. Mashery was the original choice for this task, but there are some limitations: some types of customers don't need to see all of the API in the library, and different business units have different goals for this developer platform when it comes to sales and marketing. What solutions work best to provide scaleable, customizable access?

50 comments

  1. It is by will alone I set my mind in motion. by Anonymous Coward · · Score: 0

    It is by will alone I set my mind in motion. It is by the juice of sapho that thoughts acquire speed, the lips acquire stains, the stains become a warning. It is by will alone I set my mind in motion.

    1. Re:It is by will alone I set my mind in motion. by Anonymous Coward · · Score: 0

      I must not fear.
      Fear is the mind-killer.
      Fear is the little-death that brings total obliteration.
      I will face my fear.
      I will permit it to pass over me and through me.
      And when it has gone past I will turn the inner eye to see its path.
      Where the fear has gone there will be nothing. Only I will remain.

  2. You are Doomed by frovingslosh · · Score: 5, Insightful

    and different business units have different goals for this developer platform when it comes to sales and marketing

    When you let sales and marketing drive technical decisions, brace for failure.

    Years ago I worked for mini-computer maker Data General (a.k.a "Data Who"). One of the things that took down that company was the the engineers, architects and designers built amazing technology that was far ahead of anyone else. Then marketing would come in and say "Fantastic! Great Job! Now we just need you to remove this feature and that feature, because. as it is. this machine out preforms that bigger, older, more expensive system that we are already selling." Look where that company is now.

    --
    I'm an American. I love this country and the freedoms that we used to have.
    1. Re:You are Doomed by khasim · · Score: 1

      My problem with tying it to sales and marketing is that now I will be inundated with sales calls and emails.

      And then they will sell my contact info to anyone who will pay for it.

      So I have to go through the effort of registering ANOTHER fake email address with GMail prior to filling out the form.

      Fuck, just look at how stupid Dice is making /. now. That always happens when sales and marketing interfere with technology.

    2. Re:You are Doomed by antiperimetaparalogo · · Score: 0

      and different business units have different goals for this developer platform when it comes to sales and marketing

      When you let sales and marketing drive technical decisions, brace for failure.

      Years ago I worked for mini-computer maker Data General (a.k.a "Data Who"). One of the things that took down that company was the the engineers, architects and designers built amazing technology that was far ahead of anyone else. Then marketing would come in and say "Fantastic! Great Job! Now we just need you to remove this feature and that feature, because. as it is. this machine out preforms that bigger, older, more expensive system that we are already selling." Look where that company is now.

      While your point is wise (and from experience, so i respect it even more) this "sales and marketing drive technical decisions" is unavoidable, plus not exactly correct in your example, since you could say that S&M respected R&D technical decisions (they even congratulated you!) but after that, what and how they wanted to sell it's their job, not yours - you may be right about the reason of the company's failures, but in many cases removing/delaying to release features is good *business* tactic (it happens all the time - "competing with yourself" is good for sports, but...).

      --
      Antisthenes: "Wisdom begins by examining the words/names." - excuse my English, i am (slightly...) better with my Greek!
    3. Re:You are Doomed by Kkloe · · Score: 1

      this, but even it seems that they want a system that they can offer x apis to customers and then charge them more to use other apis they might have, and that is a sound business model if it works out for them

    4. Re:You are Doomed by GerryGilmore · · Score: 2

      As a former DG-er myself, I can only agree. The MicroNova *could* have been part of a real breakout for DG, but the bigger iron guys shuddered at the lower price of it so it remained a red-headed stepchild, clearing the way for TI and Intel. After that, its 63077 for DG. :-)

    5. Re:You are Doomed by Bengie · · Score: 1

      in many cases removing/delaying to release features is good *business* tactic

      Artificial limits is just a sign of poor management.

    6. Re:You are Doomed by antiperimetaparalogo · · Score: 1

      in many cases removing/delaying to release features is good *business* tactic

      Artificial limits is just a sign of poor management.

      I don't fully disagree with that, but consider this case: for financial reasons (e.g., predicting that in the future some assets will be devaluated) R&D gets a huge budget and deliver a product way beyond of what your competitors will have in the far future - from a business point of view it may be a good idea to exploit that investment by gradually releasing features.

      --
      Antisthenes: "Wisdom begins by examining the words/names." - excuse my English, i am (slightly...) better with my Greek!
    7. Re:You are Doomed by Forever+Wondering · · Score: 1

      If you're old enough to remember the micronova [I'm a former DG software engineer and I wrote code for it], you can probably remember the PC "turbo" switch. When IBM realized that PCs were outperforming their mid-range business systems (AS400???), they changed the BIOS to prevent boot if the PC ran too fast. Hence, the turbo switch: Run slow until BIOS is done, push turbo switch to get faster clock speed.

      That was IBM's first attempt to control [PC] turf. The second came with the micro channel architecture (MCA). Their proprietary licensing caused clone mfgrs to revolt and form a standards organization that produced the ISA bus. Eventually, IBM lost control of a market it created.

      Same thing is happening with MS. Tried too hard to map everything back to Win*, even for mobile. Now, they're late to the party and are open sourcing .NET--but it's too late. Mindshare [among developers] has already headed to Android/IntelliJ/etc.

      --
      Like a good neighbor, fsck is there ...
    8. Re:You are Doomed by Anonymous Coward · · Score: 0

      As a former MicroNova customer, it would not surprise me if DG's failure had something to do with their playing hardball with the customers. Some things we dealt with gave a sharp edge to the DG advertising slogan: "We take care of our own."

    9. Re:You are Doomed by Bengie · · Score: 1

      If you've already turned a profit, then your left over crap could be destroyed and you'd still be fine. At this point you're not trying to be profitable, you're being greedy. It's normal for my company to announce discontinuance of a product and eat the "loss", nearly give away the old stuff just to make room and not waste old product. We always just release the latest greatest asap. We nearly have our market cornered and we're more profitable than the competition.

      We focus on quality and our competitors can't figure that out. Pretty much the only people that go to our competitors is because of price(literally could not afford us), but eventually they come to us and we get told about how horrible the experience was with the other people. We've even been complimented by our competitors during the few times we've had to collaborate for very special reasons.

      It's hard to get a company started when you focus on quality, but once you're there, you rake in the money. As soon as your get greedy, it's a race to the bottom and you're not longer special. At some point you will be the same as all of your competition and all you can do is compete on price. Enjoy your slim margins.

  3. tyk by MartinG · · Score: 1

    https://tyk.io/

    --
    -- MartinG To mail me: echo kewyjlcxyzvjfxbqwh | tr bcefhjklqvwxyz .@adgimnoprstu
  4. Oh fuck off.... by Lunix+Nutcase · · Score: 2, Informative

    Was your job at Dice Holdings, Incorporated, Mr. "Anonymous" Reader?

  5. Dice, please suck my dick. by Anonymous Coward · · Score: 0, Funny

    It is the only thing I'd ever be happy with you doing. Thanks

    1. Re:Dice, please suck my dick. by Lunix+Nutcase · · Score: 2

      I wouldn't be so sure of that. If they are as competent at blowjobs as they are at UI design, you'll probably end up with a chunk of your cock bitten off.

    2. Re:Dice, please suck my dick. by MightyMartian · · Score: 1

      On the plus side, you will have a share link available so you can share pictures of your shortened penis with your friends on Facebook, Twitter and Google+

      --
      The world's burning. Moped Jesus spotted on I50. Details at 11.
  6. What the #%@& !!! by Anonymous Coward · · Score: 0

    and different business units have different goals for this developer platform when it comes to sales and marketing

    What the hell is this, amateur hour? Either everyone needs to get on the same page, or separate companies need to be formed to market and sell this Swiss-army-knife of APIs to the disparate sales and marketing goals of these different business units. How the hell does a business unit within a company have different sales and marketing goals than the parent company? Oh yeah, they don't or the whole company fails! Sounds like you need to find a new job with a company that isn't run by complete morons.

    1. Re:What the #%@& !!! by Anonymous Coward · · Score: 0

      No, it's a fake question written by a Dice.com employee.

  7. Obviously by MightyMartian · · Score: 5, Funny

    Well, obviously any API management system needs a "share" button at the bottom of each screen so you can share your favorite API methods with your friends on Twitter, Facebook and Google+.

    --
    The world's burning. Moped Jesus spotted on I50. Details at 11.
    1. Re:Obviously by Anonymous Coward · · Score: 0

      why fiddle with buttons:

    2. Re:Obviously by Anonymous Coward · · Score: 0

      "why fiddle.."
      <body onclick="share_this()">

    3. Re:Obviously by davester666 · · Score: 1

      why wait for the user to click...share the page automatically when it loads.

      --
      Sleep your way to a whiter smile...date a dentist!
  8. WordPress is by far the best tool for your needs! by Anonymous Coward · · Score: 0

    World hunger, time travel, and eradication of diseases have all been accomplished by using WordPress! Ask a ridiculous question, get a ridiculous answer. Good thing you're an intern because after 3 months of nonsensical bullshit you'd be ready to quit anyway.

  9. Farewell old comment count links by Anonymous Coward · · Score: 0

    Farewell. You did nothing wrong and you were just fine. It's faggots at Dice who masturbate to change for the sake of change.

    1. Re:Farewell old comment count links by Lunix+Nutcase · · Score: 1

      But now I can more easily share links on social media! Just what not a single Slashdot reader was clamoring for all these years.

    2. Re:Farewell old comment count links by Anonymous Coward · · Score: 0

      Clearly someone at dice is getting paid based on how many times slashdot stories get myspaced and facetweeted.

  10. A Programming Interface for APIs? by Anonymous Coward · · Score: 0

    Sounds like its bigger on the inside.

  11. Actual Suggestions by icars99 · · Score: 2

    I've seen a few very good ways of doing this, but recently two products have grabbed my attention. Apigee.com used to have a amazing free service for exploring apis for various sites (like facebook and others that I've had to use). I can't seem to find a good link to it just now. However the product that I use at work for this is Postman (www.getpostman.com)

    1. Re:Actual Suggestions by I4ko · · Score: 1

      Axway API Gateway Portal (or whatever it is called these days, formerly Vordel) has the portal and the test sandbox built into each instance.

  12. Let me fix one requirement for you by xxxJonBoyxxx · · Score: 4, Insightful

    >> some types of customers don't need to see all of the API in the library

    Don't try to go down that road. If you start hiding functions through obscurity, they will pop out anyway (through code samples, forums, reverse engineering, pentesting, etc.) and will only lead to bad things (developers pissed at you for "crappy, incomplete documentation," customers laughing at you for "trying to hide the best stuff," salespeople people yelling at you for not exposing something you've already written but they didn't know they needed until they walked out of a customer meeting, top executives yelling at everyone when a security researcher finds a big flaw in a rarely used function call that everyone forgot about).

    Signed,
    Dude With 15 Years Experience With Web APIs
    (Who Has Had Much Of This Happen To Him Or His Company)

    1. Re:Let me fix one requirement for you by Anonymous Coward · · Score: 0

      ^agree with parent.

      Publish the whole thing and make sure it is all well documented.
      When we evaluate products, one thing I always look for is a well documented API with full functionality.

      Then endure your internal developers use it and eat their own dog food.

    2. Re:Let me fix one requirement for you by elmo.com · · Score: 1

      Enterprises have public and protected APIs - even if you document both you may have different provisioning flows - protected may require approvals (so someone checks that you are indeed a partner) while public may be more straight forward through a self serve signup process

  13. Dear Slashdot, by TeknoHog · · Score: 1

    please do my job for me. Thank you.

    --
    Escher was the first MC and Giger invented the HR department.
    1. Re:Dear Slashdot, by Anonymous Coward · · Score: 0

      More like:

      Dear Slashdot,

      Please answer these "challenging technical questions" so we can then try to recruit your for our partner companies.

      Sincerely,
      DICE
      (p.s. beta is awesome)

  14. APISpark by emblemparade · · Score: 1

    There are a few services that can help you.

    Check out APISpark (made by the Restlet team). It lets you publish and manage the API on the web, supports a lot of standards, and also has tools to actually help you create clients and server implementations.

  15. Are you sure you want an API management system? by Saanvik · · Score: 2

    Sounds like you are just looking for a good documentation tool, one that allows people to test the APIs live.

    If that's what you want, then you should look at API Blueprint, RAML, and Swagger.

    1. Re:Are you sure you want an API management system? by Anonymous Coward · · Score: 0

      +1 for swagger .. I've used it several projects

    2. Re:Are you sure you want an API management system? by elmo.com · · Score: 1

      You want to project the actual APIs that you offer so you want to connect to the API management system that acts as the system of record for your APIs, otherwise you will fall out of sync

  16. A hypermedia API is self-documenting by diamondmagic · · Score: 2

    The Web is designed to not need APIs or dedicated documentation. You might have heard of REST - it's a set of constraints on network architecture designs, which are: client-server protocol, layered interface, caching, stateless connections, code-on-demand (e.g. Javascript), and a uniform interface (e.g. HTML). REST is defined by the principal author of HTTP, Roy T. Fielding.

    Lots of people call themselves RESTful (Amazon, Twitter) but aren't even close. A RESTful service is pretty much just like a website: You enter at an entry point, then start following hyperlinks and filling out forms to manipulate the state of your client and the server (respectively).

    If you have an existing plain-old-HTTP API, you might want to build a hypertext interface on top of it that users can browse and submit documents with. Use a hypermedia data format like JSON-LD, Hydra, or JSON Hyper-schema to expose machine-readable hypertext. HTML is perfectly fine too, and preferable if you want to navigate the API with a Web browser.

    See:

    http://martinfowler.com/articl...

    https://web.archive.org/web/20...

    http://www.amazon.com/RESTful-...

    --
    Wonder what the public key field is for?
    1. Re:A hypermedia API is self-documenting by Saanvik · · Score: 1

      Since you don't have to implement ever aspect laid out in Mr. Fielding's dissertation to be RESTful, I think your second paragraph is a bit too strong.

      One thing that's probably not clear from your comment is where you talk about forms. A RESTful API doesn't provide forms, but it may support POST/PUT HTTP verbs, actions that are most often exercised by using forms.

    2. Re:A hypermedia API is self-documenting by diamondmagic · · Score: 1

      All the constraints of the dissertation are required to call your HTTP service RESTful; although some of the constraints themselves are 'optional', e.g. Code-on-demand (your server doesn't have to actually use it, but your protocol must support it).

      See my second link for an analysis of why the Twitter and Amazon APIs are not RESTful. Mostly, they don't implement the uniform interface, HATEOAS in particular. They don't provide hyperlinks, but instead you have to read their public documentation and hard-code your application with platform-specific URL patterns.

      To implement HATEOAS, Twitter could opt to emit a machine-readable URL template (e.g. , or the URI Templates standard). They don't even do that, except on their website, which does provide forms to write a tweet, retweet, shows links to view context, and similar. This means Twitter's own website is more RESTful than their (so-called) REST API.

      --
      Wonder what the public key field is for?
  17. Publish everything by Anonymous Coward · · Score: 0

    Don't go play hide and seek with interfaces, just document everything properly and publish it for all to see.

    This, by the by, is a core thing at Amazon: No matter what the API or the mechanism used to access it, document the whole thing, hold nothing back. NO HIDDEN APIs. It works. The question isn't "what does this customer need to see?" but the question is "what do we publish? it needs documenting."

    Playing hooky with your customers and what information about your products they can access is what redmond does by reflex, and the results are widely known: Brittle software full of "internal" access methods and a well-deserved reputation for being hateful asshats that they will be struggling to get rid of for a long time yet.

    Choose your own adventure: Which choice will you pick?

  18. HP Systinet by Anonymous Coward · · Score: 0

    Take some Everware courses while you are at it.

  19. Man pages by manu0601 · · Score: 1

    Man pages worked nice to describe the POSIX API and all its extensions. Old fashioned, not sexy, but we target developers, right?

    But I have hope it could be seen as bankable by management.

    1. Re:Man pages by Anonymous Coward · · Score: 0

      how much troff did you ever write?

  20. Something this reminds me off by samantha · · Score: 1

    Back in the 80s I built a persistent OO systems with sophisticated ACL. We implemented it by finagling the message dispatch mechanism to make select methods on guarded classes error out instead of doing what they normally did. That was on Objective C so it was fairly easy to get to the dispatch table. Some equivalent of that plus a filter on what objects were returned pretty well did it.

  21. Change might be unrealistic by Anonymous Coward · · Score: 0

    If most of the code is already annotated to generate documentation for an existing tool, then it may be a lot of work to change to a different tool.
    Doxygen, Javadoc, and Sphinx are tools that can be used for generating API documentation.
    It really depends what language you are generating API docs for, and what the quality of existing interface documentation in the code is like.
    Whatever you do, I think the key thing is to make sure that API level documentation is generated from the code, so that documentation gets maintained with the code.

  22. Roll your own... by microTodd · · Score: 1

    At my old company, we rolled our own system using perl (or python or ruby or whatever you want) and Doxygen and autopod. This made a Javadoc-ish-looking website. Doxygen is pretty powerful in what is generated, based upon the source code decorators. So we nightly generated the HTML from our git and hg repos and threw that html docset into a templating system a web designer made for us. And we were able to make one doc set using only APIs that had certain keywords or @public=true in the comments, and then another website that revealed absolutely everything for the internal developers.

    And to be honest it wasn't that hard. Maybe 2 days of scripting to get it done.

    --
    "You cannot find out which view is the right one by science in the ordinary sense." - C.S. Lewis on Intelligent Design
  23. Can you access your APIm service via APIs? by elmo.com · · Score: 1

    If your APIm service does not open APIs it will be very hard to build a developer portal that suit your needs. We work with IBM APIm, all developer portal functions are exposed via APIs and they ship an example in Drupal that you can shred apart and see all the APIs in action