Runscope API Monitoring    Learn More →

Posts filtered by category: hypermedia

An Inside Look at 7 Standout APIs

An Inside Look at 7 Standout APIs

By Ashley Waxman on .

Being an API service provider, we’re constantly on the lookout for how developers are building better APIs. As an API consumer—we rely on dozens of APIs internally and externally to power our business operations—we appreciate well designed APIs that are easily discoverable with a clean interface and quick ways to get started. This year, 7 APIs stood out to us that met all of these considerations.

We chatted with the people who have their hands and hearts in 7 leading APIs to get a peek behind the interface at the challenges they face and the solutions they use. These APIs have...

Read More →

Categories: apis, api ecosystem, community, customers, hypermedia, testing, monitoring


Create API-First Web Apps with API Platform, a PHP Framework

By Neil Mansilla on .

Every programming language is subject to scrutiny, and PHP is no exception. While often pegged as an all too basic language forged some time during the Gilded Age, PHP has done more than just stand the test of time—the language and its ecosystem have continued to evolve. In fact, one article cites that PHP has over 25 web application frameworks (10 with recent version updates), eclipsed only by Java with 37.

Just last week, PHP added yet another web application framework to the fold, Dunglas’s API Platform (DAP). Developed by Symfony core developer Kévin Dunglas, DAP is an API-first web framework built on top of Symfony, one of PHP's most popular frameworks. DAP embraces hypermedia and open standards, like JSON-LD, Hydra and Schema.org

Even though DAP is in its early stages (currently beta), it shows a lot of promise in becoming a very useful framework on its own, or at least one that influences developers to pursue an API-first development approach. Built on top of the full-stack Symfony framework, DAP gives you access to an enormous library of Symfony bundles (including bundles for OAuth and JWT).

API-first Development

About six years ago, the concept of mobile first was born, recognizing that we’d be consuming more content and using more apps on our mobile devices than on our PCs/desktops. In 2014, we crossed that inflection point. And in recent years, designers and developers have recognized that data and services are being consumed across a growing number of platforms and devices, bringing us to a new concept—API first development, which prioritizes building well-designed, architected and robust APIs before building the apps that consume them.

Getting Started with API Platform

Even if you're not a PHP developer, you'll be able to follow along with how to use DAP. Begin by creating a hypermedia API. Dunglas recommends defining your model using Schema.org vocabulary to avoid re-inventing the wheel. Though you’re not required to use Schema.org nor the generator, doing so will deliver fully generated PHP entities complete with type documentation, ORM mapping and validation annotations and much more. Before you begin customizing and optimizing, go through the process laid out in the README to better understand where your hand-crafted customizations are needed.

Generation Tools at your Fingertips

After defining your schema in YAML, run it through some of DAP’s bundled tools. First, you’ll use PHP Schema, a bundled project component to generate the PHP entities that represent your data model. At this point, you can start making code customizations to the entities.

Next, you’ll use Doctrine ORM (also bundled) to create the database and generate the tables for your API. Doctrine is optional and in fact, using a database is optional. However, while you're investigating DAP, use the bundled ORM as well as a database to observe all of DAP's functionality.

One Step to Creating Docs

Using another bundled tool, DAP generates nicely formatted Swagger UI-like documentation. The docs are available at the /doc endpoint as soon as you launch the server. Each parameter shows well-defined types of docs inherited from the Schema.org vocabulary. In the example below, we use the schema configuration for a blogging app, with blog posts and people (authors) as the main resources.

Getting Down with REST

Now that the API is up and running, you can start executing calls. Some features that you get out of the box are a series of CRUD operations through RESTful methods, request validation against the schema, error handling and more. In the example below, we take an empty resource (/people), POST a new record, GET the collection and then DELETE the person we just added.

Now, Start Coding!

After you've defined, generated and stood up the API, it's time to build the client application. The author has included an AngularJS integration, but can easily work with any client technology such as Ionic, React or your favorite native mobile framework.

What's Good, What's Next

Dunglas's API Platform framework serves as a great introduction to the concept of API-first development. It's also a swell introduction to hypermedia APIs, with support for Schema.org, JSON-LD and Hydra.

For more information about DAP check out the project repo.



Categories: apis, howto, community, api ecosystem, hypermedia


Moving Beyond the Browser with JavaScript and Hypermedia

By Darrel Miller on .

Despite their momentum, browser based applications are not killing native applications, and it seems I am not alone in believing that there remains a place for both. However, what does the client platform of the future look like? I recently read Eric Elliot's The Two Pillars of JavaScript, which opened my eyes to a different way of using JavaScript and how it and other tools are a perfect storm of tech for the next generation of native applications. I expect that hypermedia-driven, Node.js applications will play a significant role in the future of client applications.

JavaScript, The Right Way?

I’ve never been a big fan of JavaScript, or more accurately, I am not a fan of how people use JavaScript. However, the way that Eric describes how JavaScript should be used makes far more sense. I can now see JavaScript as bringing something new to the table other than just easy deployment. One of the pillars he describes is called Objects Linking to Other Objects (OOLO). This concept resonates with me because it mirrors using hypermedia to connect resource representations. A significant amount of my work is geared toward helping developers leverage hypermedia to make client applications more dynamic and more evolvable.

There are Types, and then There are Types

Eric laments the fact that much of the JavaScript community tries to pull the notion of classes into the language. This notion reminds me of how the REST community attempts to bring domain types into REST representations. Typed systems have significant value and work well within a controlled environment. However, creating contracts between components of a distributed system have a very different set of constraints.

The Language of the User Agent

Eric describes JavaScript as having a dynamic nature and cross-platform support, which makes it an ideal language for building user agents to consume REST-based services. JavaScript also streamlines the transition between deployed client code and REST-style code-on-demand.

In the past, JavaScript was limited to executing inside a web browser. Web browsers are useful if your primary goal is to build an application that can easily be delivered to many platforms and devices. However, if controlling the user experience is critical, then web browsers are not optimal.

Node.js is an environment that allows JavaScript to run outside of the browser. The majority of the focus on Node.js so far has been as a server-side platform. Yet its potential as a client framework seems far more promising to me.

On the Client?

If you are not building applications inside a web browser, then likely you will need some other framework to provide commonly required client infrastructure.

Electron, formerly known as Atom Shell, is a framework for writing cross-platform desktop apps using just HTML, JavaScript and CSS, and has a large user base, including GitHub, whose Atom editor is built on Electron. Slack’s Windows client uses Electron and performs well and is extremely reliable.

Even Microsoft’s new Visual Studio Code editor is built using Electron, and has been good enough to displace Sublime as the editor of choice for one of my coworkers on his Mac. Also interesting is that Microsoft announced that it will support a version of Node that will run on its Chakra JavaScript Engine on ARM processors. This allows Node to move to many more mobile devices.

The fact that Node is single-threaded and uses and event-driven model is ideal for client UI development. Like Gregory Young mentioned in a recent talk, it's like VB3 all over again!

HTML vs. XAML

As a developer who spent lots of time building forms over data and line of business applications, I've never been a fan of HTML/CSS for UI layout. Every time I tried to do something slightly complex, it was painful. I always found XAML-based UIs much easier to do the types of layout I wanted to do. However, from what I've seen and heard, Flexbox is the piece that has been missing.

I still think XAML has certain advantages over HTML, but Microsoft has made so many missteps with its handling of XAML UI implementations over the last eight years that I'm not sure it will ever recover. It's a shame that now Microsoft has finally realized the value of XAML for its universal app solutions, but it requires you to upgrade all your Windows devices to Windows 10. It's great that Microsoft is finally heading in what I think is the right direction, but it will take another five years to fix the mess it has made.

Having said this, another post by Eric discussing JSX points out that React components can emit any kind of XML style markup. One has to wonder if there potential for a JS/XAML partnership in there somewhere. And let’s not forget that Xamarin is still a strong supporter of XAML in the cross-platform mobile space.

A Perfect Storm of Tech

We are approaching a point where there is a critical mass of people and tools that are ready for the next generation of native applications that will be just as much a part of the web as the browser is today.

Are you building a client that runs in the browser or in Node.js on the server side? Try Runscope free for live API debugging and traffic inspection. For more of my insights on Microsoft, hypermedia and APIs, visit my blog.

Categories: apis, hypermedia, api ecosystem


Hypermedia, Past, Present and Future

By Darrel Miller on .

Hypermedia APIs are beginning to enter the mainstream of API development.  For developers trying to get up to speed on hypermedia there are a dizzying array of terminology and choices. This blog post gives an overview of the hypermedia space, giving some perspective on where we have come from, what has been tried, what has worked, what has not, where the industry is headed and what questions remain unresolved.  Read more here...

Categories: hypermedia, api ecosystem


API Craft 2014 Conference Recap

By Darrel Miller on .

The agenda.

The agenda.

Earlier this week I headed to Detroit for the second annual API Craft Conference. Being my first time I didn't know what to expect, but I knew many of my fellow API design aficionados would be on hand and I was eager to learn from the many smart attendees.

Day One: Hypermedia in Focus

This year's API craft started with a Hypermedia Panel. The creators of all the most popular hypermedia formats were on the panel and they all had an opportunity to do a short presentation. The event was streamed and recorded.

One of the most important takeaways for me from this panel, was that there is a growing appreciation for the fact that hypermedia is more than just defining passive relations between resources.  Abstracting behavior behind hypermedia links is an equally valuable scenario.

Days Two and Three: More than Just Hypermedia

As an open spaces conference, the second day started with people pitching ideas for sessions. I was particularly interested in the sessions relating to ways of communicating semantic meaning because I believe that is one of the biggest remaining challenges in API design. Some clear themes emerged from the session proposals: testing, measuring, monitoring and managing of APIs was well represented, as well as plenty of sessions around making the business case for APIs and especially hypermedia APIs.

The rest of the day was jam packed with valuable sessions and conversation. I learned about the variety of different ways people map their domain to resource models in Glenn Block's session on Web API architectures. In the API testing session run by Kevin Shamoun it was interesting to hear the tools developers were using and the challenges they were facing.  Kevin Swiber held a very well-attended session, amusingly named 'Why y'all hatin' on hypermedia?' where we discussed commonly heard objections to hypermedia and solutions to overcome those objections. 

During the closing discussion, I asked the attendees how many were already working on hypermedia based solutions, and I would estimate between 30-40% of hands went up.  This is a huge increase from what I have seen in the past.

Despite the abundance of hypermedia content, there was plenty of discussion on topics like security, testing, monitoring, management, design, diagramming, mobile, IoT, and many more topics.  The proceedings for all the sessions are being recorded in the Github wiki. 

Overall, my three big takeaways from the event were:

  • Hypermedia is finally getting mainstream attention.
  • The level of expertise in HTTP API design is significantly improved from a few years ago.
  • There continues to be a big demand for HTTP API related libraries and tooling, especially on the client side.

API Craft was a great conference and I'll definitely be reserving the dates on the calendar when next year's event is scheduled.

Categories: events, hypermedia, api ecosystem


Everything is going to be 200 OK®