We are about halfway there now, with the following completed:
Routing
Templates for different page layouts
Resource development page
Drag ‘n’ Drop interface
Lists of processors (nodes) in the system
JSON view
YAML view
Ability to switch between the views with data loss
Import/Export resources locally
Processor info slideout drawer
Ability to enter input constants
Centre and zoom the view on the existing design
Re-order the nodes in the GUI
Applications page
Notifications modal
Home page
Unit testing (Vite)
E2E and Component testing (Cypress)
Styleguide (yarn styleguide)
Jdoc (yarn jdoc)
Theming
Light/Dark mode
The develop branch on ApiOpenStudio core has been updated to include a refresh token. This extends the JWT functionality, so that when the existing login token expires, the user does not need to log in again (unless they have been away for over 1 week).
The next phases includes:
Adding unit tests for the conversion between Drag ‘n’ Drop data to JSON/YAML
Login & token refresh functionality
Replacing stub data with real API calls from an ApiOpenStudio core instance
The latest off the hot-press: We have finalised and published the docker creation pipelines. This now means that you will continually have the latest version of ApiOpenStudio Core and Admin images at your fingertips.
The images are very fast and easy to install and completely self-contained (server and all requirements, including Composer dependencies). That means that you do not need to install any infrastructure on a barebones server, except for Docker, config file and SSL certificates. See:
The scripts are configured to generate images from tags or any branches we want to release (this includes develop/master branches and any development branches that we deem necessary for testing).
Full documentation of the installation process is available on our wiki at:
The scripts are available at the GitLab docker repository (Core and Admin), and I’ve also taken a little time out to post a gist of one of the scripts that others may find useful (download a specified branch or tag from a GitLab or GitHub into a location) at https://gist.github.com/naala89.
APIs are displaying continued astronomical growth (see https://www.postman.com/state-of-api/api-global-growth/#api-global-growth) and are now a critical part of nearly all modern architecture. However, we have seen a lot of coverage recently of the different terms encompassed by the API First methodology, especially as people try to use these buzz-words to generate excitement over their products without fully understanding what they mean.
In IT, terms tend to evolve, due to the pace of change. But this is not the ideal way to create terms as it can lead to similar terms, causing sub-optimal communication, even mistakes. But unlike industries like aviation and maritime, which are the gold standard for communication, w do not set a standard and declaration for what precise terms to use and when, to prevent confusion, misunderstanding and planes and boats crashing into each other.
For instance, we now have the following:
(Yes, I know that some of these are unrelated to APIs, however there is a real problem with language here – everything sounds the same and confuses people)
I don’t know about you, but my head is rattling from all of these variants. This is getting ridiculous and incredibly confusing for everyone, requiring a lot of reading of articles to understand the nuances of the new terms that are being introducing and how these may subtly differ from the others.
As technologists, we need the business community to fully grasp the ideas and benefits behind the API first methodology so that we and they can make sound judgements on directions and strategies. This means that the ideas need to be immediately comprehensible and their ramifications obvious.
I am going to suggest that we throw out a lot of these phrases and keep things simple, but I won’t try to reinvent the wheel and create completely new phrases. For the rest of this article, I will only refer to 3 terms.
API First concepts
Each term has an impact on the technical and business strategies/successes in different measures. But each concept requires a full “buy-in” and understanding from the business.
API First
Design the and build the API first!
The product is built around the API.
This is reflected in the business strategies and revenue models (see API as a product and API design 1st).
API-first is obvious from the business point of view. The API is the primary income generator or essential to other income product/s. Without a revenue model, you do not have a business. Therefore if APIs are the main product or critical to a product that is being created/overhauled, then the API becomes a crucial first-class citizen, not just for the technical dept, but also from the business.
Information and data are key to the modern business, right? APIs are the backbone for nearly all data communication.
Building a new product (not just API) is an expensive task, both in time and money. By going through a full design phase for the API, the correct emphasis and attention is given to the API that it needs, a lot of thought will be put into:
What data is being shared across the API.
Why this data sharing is required or wanted.
Who/what will be consuming the data (internal and/or external).
This will reveal any potential flaws or opportunities in assumptions that the business has made.
Ensuring that all business processes are made more efficient by the new agile data flow that APIs will provide.
Performance.
Reliability.
Scalability
Usability.
pricing.
Future changes/versioning.
n return, API First will have a causal effect on the business by ensuring that due diligence and research is followed before embarking on a costly venture of system build. A lot of thought will be put into what the business needs and why. Future projections and plans become much clearer.
This does not mean that all other resources sit in idle-mode until the API is built, in fact it can happen simultaneously. Once you have the API model built in documentation like OpenAPI or Redoc (quite early in the process), you have a model that can be used by consumers before you start the full development. This saves time and money on fixing broken assumptions, missing or inadequate requirements.
API as a Product
The API may be the core product, but not necessarily.
API as a product has 2 definitions:
External-facing API that is monetised
Indirect monetisation by a product that requires an API to function or public exposure and usage through a free public API.
API as a product, is tightly coupled to the API design-first concept. In order to implement business strategies for revenue driving APIs, good design and documentation is a “must-have” to enable third parties to consume the APIs, providing an easy-to-use, comprehensive and unified experience.
If the API product is well designed and documented, this will increase the consumption and efficiency of the API (and therefore income). Postman alone has seen very significant increases in traffic and API usage, despite the global downturn and Covid:
Since the 2021 State of the API report was released, the Postman API Platform saw significant surges in use: * Users: 20 million * Collections created: 38 million * Requests created: 1.13 billion
In general, this is a development model for APIs that ensures the following criteria are met:
Reach agreement from all stakeholders.
Design the APIs models first on OpenAPI or similar product.
Build the API.
Separate products can be built at the same time as the API.
API design first may not be quite so obvious from the business POV, because at first view, it is just a development process. However, because it requires approval from all stakeholders, it is critical to have business “buy-in” to the process. This enables all of the business to see what/why the API is being built, and ensures that everyone is agreed on the most critical features they need.
In addition, this results in a rare instance of a complete understanding of what is being built and why, by the technical department. Instead of just being told to “build this” by the business without any consultation between them on what the rationale is, what is technically feasible, or if there is a better solution, the developers and department see the vision and are able to work towards that vision in a much more efficient manner and the end result will be a much better product.
Conclusion
This all ties in with discoveries and revelations being made about “Developer Experience”.
Up until recently, a lot of research and time has been invested un user experience (UX) and there is no denying the value that this can contribute to the business by increasing traffic and revenue. However a new key realisation is being made about developer experience (DevX). Who will be directly interacting with and consuming the APIs (and therefore making critical decisions that will impact their business about what APIs to consume and the frequency)? That right, developers!
They will correctly discard badly documented or difficult to use APIs in favour of better APIs. This means your product will be directly impacted by the DevX experience!
If you are supplying an external facing API for revenue (direct with monetisation or indirectly by offering APIs free with the associated traffic, publicity and exposure), then DevX is crucial to maximise income.
If you are supplying an internal facing API, then good DevX will have an impact on associated systems design, development and maintenance. Business processes that interact with the API will be either made more efficient by a well designed API or made cumbersome slow and inefficient by bad APIs.
The findings in this report are golden and kudos to the PostMan team for producing a well-balanced and researched report (https://www.postman.com/state-of-api/, 2021).
Its findings are highly encouraging, and reading between the lines, are a fantastic indicator that the industry is on target for a continued adoption of mobile-first, API-first and micro-service architecture.
Our key take aways from this report:
The API ecosystem is global and growing
Postman reports continuing growth in API activity:
Users: 17 million
Collections created: 30 million (up 39%)
Requests created: 855 million (up 56%)
There are many more people, other than developers using APIs
Breakdown of roles consuming APIs
Developers are spending more time with APIs
< 10 hours/week: 33%
10 – 20 hours/week: 39%
> 20 hours/week: 28%
This was a rather surprising set of stats, and probably due to the respondents coming from API driven developers.
API first methodology
Encouragingly, there is increased awareness of the API-first methodology, and more businesses are approaching their architecture in this way:
Companies embracing API-first methodology
Sadly, there was an inconsistent or lack of understanding of what API-first actually meant:
Defining API-first
Public vs Private vs Partner
Of interest here is that the vast majority of APIs are intended for private use within companies. This ties-in with the API-first methodology, where APIs are considered first-class citizens in the (Understanding the API-First Approach to Building Products, 2021)
APIs are treated as “first-class citizens.” That everything about a project revolves around the idea that the end product will be consumed by mobile devices, and that APIs will be consumed by client applications. An API-first approach involves developing APIs that are consistent and reusable, which can be accomplished by using an API description language to establish a contract for how the API is supposed to behave.
Public vs Private vs Partner
Private (only used by your team or your company): 58%
Partner (shared only with integration partners): 27%
Public (openly available on the web): 15%
Lack of time was the biggest obstacle to producing APIs
Over 45% of API developers claimed that their main impediment was lack of time.
JSON Schema is by far the biggest specification tool for APIs
JSON Schema was by far the top specification in use, cited by three-quarters of respondents
Now this one really surprised us (we had assumed it would be OpenAPI 3.0, but that was below Swagger 2.0. Considering that the API documentation standards have still not coalesced into an accepted standard, there should be no surprises in movements here, and it has to be said that JSON Schema is fantastic, especially for defining complex, nested object types.
Quality is the biggest priority for APIs, above security
Respondents identify the top priorities for their development teams and organisations
This was also a surprise to us, although it transpires that a lot of APIs consume public APIs and therefore we assume that when quality is specified, they mean quality of data and resource specification. Therefore leading to a better resource offering and more consumers of it.
The recent flood of articles discussing the way that Low-Code is changing the landscape of development have 2 key elements:
Low-Code is now clearly emerging as one of those enormous waves in tech, that will change the way that things are done across business and IT development moving forward. For both tech companies and non-tech companies (because everybody is technology driven).
In the future, it is really how these tools are used in unison with the company’s “Pro-Code” developers. Which is the real business problem to be riffed on and solved!
What does the new development environment that includes “Citizen Developers” look like? How will they interact with IT Departments and the Pro-Code developers?
Will Low-code replace Pro-code?
Up front we’d like to point out the answer here is something we are sure of. This will in no way reduce the demand or work for Pro-Code developers.
There is compelling economic reasoning for this. As while it is true that all companies want to save costs, we are in an increasing world of digital transformation, where every business is in reality, a tech business.
So the one area where you cannot start with cost saving, is technology. Companies will always be in a technology race to the leading/bleeding edge with their competition. That edge will always require having the best Pro-Code people you can get, as they provide the competitive advantage.
Paradoxically this means if you have that, you also need the best Low-Code resources for two reasons:
Low-Code enhances the output of your Pro-Code work force, doing vital but repetitive, non-challenging tasks. Speed means less hours, more output, and we all get that.
These are considerable the other benefits, beyond cost savings. One of which is the morale& job satisfaction of the Dev team. Developers universally report that in their ideal work environments, they want to be working on important and challenging tasks. Where they have the best chance of learning things along the way.
So Low-Code can reduce the time they spend on these less interesting tasks. Because you can’t make the tasks go away. The answer is to use a tool that lets you get more done in less time.
More accuracy and happier teams
The hidden part of all this is the organisation’s abilities to utilise No-Code/Low-Code and adapt to it.
In terms of moral & satisfaction, there is clear evidence that the most onerous of tasks are the organisational ones. Like storing names & levels of permission on an API, in the case of ApiOpenStudio. These often have a high cognitive load because they require high concentration but they are in no way interesting. Low-Code solutions come with User Interfaces and Dashboards and these reduce cognitive load and risk in these tasks by making the tasks simpler and providing ways of validating your entries are correct and making the editing/deleting of changes easy. So there are huge benefits in day-to-day operations.
Learning a new technology and skill can also be fun. As we know, the primary driver for nearly all employees and their job satisfaction are:
Confidence in the leadership team.
Implementing Low-Code in a balanced way will demonstrate that the leadership have a forward-thinking mentality.
The employee is valued.
Providing training in the new technology and processes will show that the business wants to keep them and invest them.
Satisfaction with daily tasks.
The employee will feel more satisfaction through more responsibility and seeing their work being visibly used.
Learning and growth.
We all want to grow and extend out knowledge and usefulness, with the additional benefits of making us more desirable to employees.
With the decision to introduce Low-Code platforms, your first issue should be governance and compliance.
Your “Citizen Developers” and Project Managers should start to deepen their communication and feedback loops. Most importantly, non-technical people have to really feel they can come to the experts with the most basic questions, even if it is just to check they are on track. This is all new to them and they are not professionals in this sphere.
Because deep, first-hand knowledge of requirements is another advantage that citizen developers brings to the table. It’s worth noting that their approach will usually be decided on the functionality that they want. The effects on governance or the rest of the architecture are normally the furthest from their minds.
So from a Project Management perspective, clear leadership is needed right at the start in setting out the processes needed on the project. So that features and functionality are plumbed in properly.
Communication
There needs to be clear communication between the citizen and Pro-Code developers (usually via the Project Manager), but this can also be direct. This will ensure that any requirements between the two teams are met and no-one is adding useless things to the system, or features that will slow down the system performance.
Once you have initiated a communications format between citizen developers and the development team, then testing and documentation can be mapped out.
Documentation
A clearly written and easy to access set of documents will be required by both your citizen developers and all levels of the development team.
This will ensure that:
Onboarding is quick and easy for citizen developers and they can quickly find answers to any questions that they have, without feeling overloaded by technical answers.
Managers and project management have access to sources of truth that enable them to answer any questions.
The Pro-Code developers are aware of the Low-Code systems and how they interact with their work.
Leaders of the development team can easily find a broad overview of the different systems, the interaction between them and the processes that have been implemented to govern them.
Quality assurance
Depending on the complexity of the No-Code solutions and their impact on the rest of the technology, it is very likely that extra guard-rails will have to be introduced. This will probably involve QA (quality assurance), the ability to import and export configuration, and the release cycles.
Even if the output of the citizen developers is content (for example: pages in a blog or CMS), there should be systems in place to accomodate proof reading and validating the look and feel on different devices. There are additional complexities here, if the content that the citizen developers create is all in a database and cannot be imported/exported – where will this be tested, how will it be released? Although this issue is usually solved by that specific technology’s community, time should be spent looking at the different solutions proposed to find the best solution for your organisation.
In the case of complex No-Code solutions that interact with the output from the development team, then these need to go through the full QA feedback loop. QA can then validate that the existing functionality is not broken and that the new functionality works as expected and different systems interact as expected.
What is important, is that that the development team should reach out to the management of the Citizen Developers, so that they can have the discussion with them about compliance and governance & how they must comply with the IT departments direction (and vice versa). This is often an issue in companies, where people directly report in their department, and are in effect silo’d from the other departments.
Moving into the era of Low-Code/No-Code enhanced Companies.
The organisations that are going to maximise the benefits of this new wave, should already be initiating broad company-wide conversations. These will range deeply across all levels of the organisation. From the way that Pro-Coder work days and productivity will be enhanced to evaluating the advantages and disadvantages of implementing Low-Code solutions for specific tasks.
This will even permeate as far as hiring & the HR Dept. As you look to harvest the advantages of onboarding people in traditional roles that have these additional skills, or incentives for current employees who wish to acquire No-Code or even Low-Code capability.
This is the conversation of the future for all companies that will succeed in this new era!
