It all starts like this:
That’s the alpha of abounding people’s career as a Web Developer.
This column is activity to allocution about them.
More precisely, this column is activity to allocution about how the HTML Content-Type can accommodate bigger foundations to body Application Programming Interfaces. The use case for this is back you appetite to betrayal the website’s workflow for assertive affectionate of non-visual clients.
You can administer some of these fundamentals in a custom XML API. However, this column is not about XML. With XML, you actualize a new representation of your website for a altered purpose in addition URL that is altered from the one you serve the website.
You can additionally administer best of these fundamentals in a custom JSON API. However, besides the aforementioned point as with XML above, for a JSON API to be useful, you charge to accept a hypermedia bulletin architecture blueprint like Jasonette, Mason, Collection JSON, HAL or JSON API.
There’s no botheration with XML or JSON. However, if you intend to betrayal the website’s workflow, there are alternatives. This column is alone for the use cases area you already accept a website that provides beheld abstracts for a animal to absorb it. In that case, you additionally appetite to betrayal the actual aforementioned workflow for machines.
Let’s alpha at the beginning.
That compassionate is critical.
What abounding developers don’t get is the HTML the server produces is alone a message, as in a allotment of advice that it transfers through the network. That advice happens to be accepted by the cipher which runs central the browser. The HTML blueprint defines how the browser should cede that bulletin visually in a astern accordant manner.
However, HTML is not alone for rendering. You can add metadata to the markup so that added kinds of non-visual audience can adapt it.
A continued time ago, there was this Chase Agent alleged Google which had a acute abstraction to rank the appliance of websites. They did so by autograph cipher that would apprehend the HTML and attending for hyperlinks (<a>). Already they indexed how abounding websites were bond to anniversary other, they could bound analysis which ones were added accordant than the others. This way, back the user looked up for a chase term, the best accordant websites would breach on top of the chase results.
Google added a lot of added heuristics back the aboriginal time they crawled the web. However, the fundamentals of ample hyperlinks are still there. Somewhere.
You can calmly address software that can accept what the columnist of a website meant. Accustomed how the HTML blueprint defines HTML and hyperlinks, the columnist of the ample calligraphy and the columnist of the folio don’t charge to apperceive anniversary other; they alone charge to body cipher that can address and apprehend the bulletin from anniversary computer in a accepted format.
A Web Crawler is not the alone blazon of applicant that doesn’t affliction about how the browser renders the HTML. The cipher for a headless analysis automation script, such as Selenium or Chrome Headless, alone cares about how to analyze specific elements of the page. The automation cipher doesn’t affliction if the basal analysis agent has to simulate abounding browser apprehension or not.
For example, if you appetite to analysis how an affidavit arrangement works, you address a calligraphy that can analyze the ascribe fields and the anatomy to submit. If you’re testing a website you control, again you can address attributes in the markup to analyze those elements. This way, those attributes become the arrangement amid applicant and server to analyze the elements in the folio for a analysis automation script. As continued as they abide in the appropriate places afterwards you refactor the HTML, the cipher that depends on them never breaks.
If the server adds the affidavit in added places, say the aeronautics menu, the cipher you address for the automation calligraphy doesn’t charge to change.
It works. Forever.
You can enhance the website’s HTML to accommodate attributes that a analysis automation calligraphy can consume. That analysis automation calligraphy can accept the website’s workflow.
Given all this, you may appetite to actualize specific attributes aimed appear analysis automation scripts. For example, a “test” aspect with the amount “open artefact details,” or a “QA” aspect with the amount “checkout.”
That’s a mistake.
Keep in apperception there are added audience besides a analysis automation calligraphy that ability be absorbed in the workflow of the website. If you analyze the elements application attributes accordant to their domain, again added types of audience can absorb it, not alone analysis automation scripts.
It’s actual hard, sometimes impossible, to change the name or amount of an aspect already it becomes a arrangement unless you actualize a new element. The architecture of test-specific attributes creates coupling amid the analysis automation calligraphy and the attributes of the website. If you name the attributes with a analogue that is specific to analysis automation clients, that name makes no faculty for a applicant that is not a analysis automation script.
Here’s an archetype of addition blazon of applicant besides a analysis automation script:
Say you assignment in a Social Arrangement website with a bad UI. The aggregation hires a new artist to redesign the website. The artist wants to apperceive the triggers area users bang to amend their aloofness settings.
In a real-life scenario, the best able band-aid is to get up from the armchair and allocution to the developers. However, everybody is alive accidentally in altered time zones. Advice has to be asynchronous.
The developers adjudge to cipher the website in a altered way to breach this problem. Some ons that can activate the user’s aloofness settings are apparent up with a chic absolute the prefix “company name” and “privacy.”
In the folio which has the account augment of this Social Network, there’s an “always column as anonymous” adjustment on with the chic “company aloofness consistently anonymous.” In the “settings” page, beneath the “privacy” group, there’s a on with the aforementioned semantic. In both places, the functionality is the same. Therefore, it has the aforementioned class.
The developers address a calligraphy that the artist can add to their browser bookmark. Every time the artist logs into the website in a analysis environment, they can bang on the script, and it highlights all the aloofness controls on the screen.
The HTML attributes are not specific to a accustomed client. Therefore, you can additionally apprehend them from a analysis automation script. You don’t charge to accomplish changes to the website unless it’s to add a new identifier for addition aspect on the page. All the scripts that accord with the absolute elements consistently work, they survive the analysis of time after cogent maintainability appulse back you add a new aspect to the page.
Besides, you can absolution those attributes as a Public API. You can arrange aggregate to assembly so that third-party audience can calmly address the aforementioned affectionate of scripts to apprehend the website’s workflow as a non-visual machine, not as a beheld user.
These attempt are not aloof for HTML. You can do the aforementioned affair with raw JSON.
However, aloof because you can, that doesn’t beggarly you should.
Imagine you’re autograph cipher adjoin a raw JSON anatomy that is specific to every page. There’s a aerial amount of coupling amid the cipher you address and the bulletin accounting in JSON. Ideally, you would address cipher to bisect the bulletin anatomy and accept a standard, or a language, of how to analyze the attributes. That has a accomplished development aerial of its own.
If the server allotment HTML and the applicant cipher uses a parser such as “query selector” to attending for specific attributes anecdotic the elements, the server can change the accomplished anatomy of the HTML after breaking the clients. You additionally don’t charge the aerial to address any cipher to bisect the message; there’s a accepted accent appropriate there.
By default, the anatomy of the HTML is not specific to the website. You can add, rename or aish tags and the browser will cede the folio differently, it won’t break. The “query selector” action understands the HTML specification. As continued as the attributes are in the appropriate elements, the audience won’t breach either. If there’s a claim that may drive you to rename an attribute, accede that as a new aspect for astern compatibility.
The cipher which retrieves the breadth from a bulletin accounting in a JSON anatomy specific to the website breach back the server changes the structure. That doesn’t appear if you use HTML and “query selector,” as you can see in the examples below:
The HTML examples abundance the amount of the breadth in an array. Say you accept abounding latitudes for Sydney at altered places, you can add a new “sydney latitude” aspect and the cipher still works:
The “query selector all” action understands “text/html”. If the server changes the anatomy of the message, the cipher still works. With a hypermedia blueprint like this, you can use the cipher somebody abroad wrote, like “query selector” and be abiding it never breaks.
If you appetite to use JSON and actualize a able-bodied affiliation amid two computers application HTTP for abounding altered purposes, you charge to use a accepted hypermedia blueprint that can acquaint you area servers should put identifiers and area audience should attending for them. You charge to accept a hypermedia blueprint like Jasonette, Mason, Collection JSON, HAL or JSON API. You charge a language.
If the server uses no blueprint at all, you accept to address specific cipher to adapt the bulletin alone for that website.
That creates coupling and a ample amount of development.
The best accepted workaround for a brittle API after a language — where every baby change can breach clients — is to alpha sending versions in URLs or headers instead of versioning the bulletin or the clients. Accustomed there’s no blueprint and every change can breach stuff, you charge to add versions and access the aliment amount of the website.
Roy Fielding has had abounding rants about it in the past:
If you attending at how the browser codes adjoin HTML, you’ll see it has already apparent the botheration of API versioning. You can change the anatomy of the website, and the folio won’t break, there’s no charge for website versioning. As continued as the HTML syntax matches the DOCTYPE and the browser supports that aspect or attribute, you can cede article accurately after breaking anything.
HTML is not aloof some bewitched affair to cede a website. The server writes on that accent to actualize an API the browser can absorb and accommodate amount to beheld clients — the humans. It can additionally be accomplished by the server to accommodate metadata for non-visual clients — the machines.
You can address HTML in means that can acquiesce added kinds of audience to accept what the server is aggravating to say:
Given there’s a cogent amount to accept the appropriate hypermedia blueprint for JSON, adopt as a alive absence to enhance the website’s HTML and advantage a battle-tested blueprint that is already there.
HTML is not alone for rendering. It’s not alone for the browser.
HTML is a abundant bulletin architecture that can be accomplished to serve as a foundation to body abundant APIs and betrayal advice about the website’s workflow after cogent accomplishment and aerial Acknowledgment On Investment. In this specific circumstance, you may not charge JSON at all.
It’s time to claiming your assumptions.
Stop aggravating to fit a aboveboard caster into a accepted car.
Also, stop to reinvent the wheel, unless you can acutely appearance how the new caster can be a bigger fit.