artofinternet

[artofinternet]

full stack architecture

front end (eg javascript)

     |  

back end (eg java)

     |

database (eg mysql)

Why? allows flexibility for multiple physical devices 

only thing that needs to be customised is the front end

Middleware is just a part of the back end in above diagram (eg restful API)

from Wiki

ECMAScript (commonly abbreviated ES) is a registered trademark of Ecma International and is itself, a weakly-typed dynamic object-oriented general-purpose cross-platform vendor-neutral interpreted lightweight high-level event-driven scripting language standard whose specification is codified internationally by ISO under the title https://www.iso.org/standard/73002.html

As a Java Developer, it is important to know the release cycles and the new features.

I have found a you tube video that summarises 9 through to 16 - https://www.youtube.com/watch?v=8hA47LxykPo

[artofinternet]

time for service design

Service design is the choreography of interactions we have with a system and typically that system is a brand. One of the keys of service design are service design touchpoints. These are the things and pressures or people that define and shape the experiences they have. Touchpoints take on a whole number of different forms. People, environment, policies, artifacts the invisible things that impact our interaction with a company.

Now to discuss this thing called time.

[artofinternet]

Enum refresher

The best definition I’ve heard of Enumeration types is as follows:

Enums are if a Class and an Array had a baby. It’s just a list of values that doesn’t change, but it’s set up as a class and you access it as a class. 

As an aside Enumerations are static and final implicitly.

You can put enums inside or outside of a class.

Enum convention is upper case and not in between quotes.

Enums are used for variables that don’t change.

Enums can have methods within them to perform operations on them such as get.

Enums were introduced with Java1.5

[artofinternet]

psychology and abstraction

there is a psychology theory that states there are three versions of you

- who you think you are

- who others think you are

- who you actually are

In terms of abstraction this theory demonstrates it perfectly in the sense that who you actually are does not have an observer one can interact with and hence is only conceptual.

Who you think you are as a concept is easy to understand because its from a first person perspective. What you think about you. 

Who others think you are is from a second person perspective and is a little more complex in the sense that there are multiple possibilities and multiple observers.

Who you actually are however is just conceptual and hence abstract.

The Johari window might be a better theory for the versions of you that exist and your relationship with others but the above is better at describing abstract types. I also quite like the irony that the actual you or the real you is abstract. Kind of makes sense in terms of computers because they are not made up of living matter.

[artofinternet]

abstract types = placeholders

I think of abstract types as placeholders or as the beginning of a framework or an idea which needs further rules added before it can be used, but always has some kind of governing rules that are always applied to the expanded actual type.

Formally though Abstract type is a type without instances or without definition.

Methods that don't have an implementation are called abstract methods in Java. An abstract class cannot be instantiated. Before Java 8, interfaces could not implement any methods and all methods were implicitly public and abstract.

Abstraction refers to the act of representing essential features without including the background details or explanations.  Abstraction focuses on the outside view of an object (i.e. the interface)

Abstract classes are classes that contain one or more abstract methods. An abstract method is a method that is declared, but contains no implementation. Note:

If even a single method is abstract, the whole class must be declared abstract.

Abstract classes may not be instantiated, and require subclasses to provide implementations for the abstract methods.

You can't mark a class as both abstract and final.

A class that contains an abstract method or inherits one but did not override it must be an abstract class; but an abstract class does not need to contain any abstract methods. An abstract class cannot be instantiated. If a method is abstract, it cannot be private.

An abstract class can never be instantiated. Its sole purpose is to be extended (subclassed).

An abstract class can provide complete, default code and/or just the details that have to be overridden.

Before Java 8 (before March 2014) an interface cannot provide any code at all, just the signature. (Before Java 8, interfaces could not implement any methods and all methods were implicitly public and abstract.) With Java 8 you can even define static methods within an interface, to be honest i have no idea why this was not allowed in the past, do and did wonder about it myself. I’ll have to do some historical investigation before I can give you any insight on that.

In case of abstract class, a class may extend only one abstract class.

A Class may implement several interfaces.

An abstract class can have non-abstract methods.

All methods of an Interface are abstract. (except not any more)

An abstract class can have instance variables.

An Interface cannot have instance variables. (pretty sure it can now)

An abstract class can have any visibility: public, private, protected.

An Interface visibility must be public (or) none. Hmm...This is currently being managed through API security i believe. From Java 9 onwards interfaces allow private and private static methods.

If we add a new method to an abstract class then we have the option of providing default implementation and therefore all the existing code might work properly.

If we add a new method to an Interface then we have to track down all the implementations of the interface and define implementation for the new method. And this is what i spent a good deal of 2012 doing, but i don’t think you need to do this any more as the owner of the API needs to manage it.

An abstract class can contain constructors.

An Interface cannot contain constructors. Constructor is not provided by interface as objects cannot be instantiated. You cannot have a constructor within an interface in Java. You can have only public, static, final variables and, public, abstract, methods as of Java7. From Java8 onwards interfaces allow default methods and static methods.From Java9 onwards interfaces allow private and private static methods.

[artofinternet]

css = presentation layer

allows us to make web pages look good.

css separates the content from presentation. allows you to add styling information to many elements at the same time. allows you to make changes to your web pages quicker. you can change the colour of all the links at once rather than changing the colour of each link individually.

css is composed of rules (css properties that are a key value pair) that act on different selectors (kind of like case statements for HTML elements). For example in below snipped  ‘p’, ‘text-bold’ and ‘first-row’ are selectors. The rules (or css properties) are what is included between the curly brackets. Each rule is composed of a rule name and the value of that rule. The font-size rule has the value of 20 points. The colour rule is red and the background-colour rule is black.

The p selector is a tag selector and selects alll the html tags which are p. the rules are applied to all of these tags. selectors with . in front are class names. the # is the ID in the HTML page. Note: you can only have one HTML element with a specific ID, you can have many elements that have the class name.

p{

font-size:20pt;

color:red

background-colour:black

}

.text-bold {

}

#first-row {

}

There are a wide variety of css selectors to choose from.

[artofinternet]

HTML forms

the beginning tag

<form action=“process.php” method=“post”>

process.php is a php file on the server. It tells the browser which file will receive the inputs from the form. From w3schools

The <form> element can contain one or more of the following form elements:

<input>

<textarea>

<button>

<select>

<option>

<optgroup>

<fieldset>

<label>

<output>

The <input> tag specifies an input field where the user can enter data.

The <input> element is the most important form element.

The <input> element can be displayed in several ways, depending on the type attribute.

From W3schools. The different input types are as follows:

<input type="button">

<input type="checkbox">

<input type="color">

<input type="date">

<input type="datetime-local">

<input type="email">

<input type="file">

<input type="hidden">

<input type="image">

<input type="month">

<input type="number">

<input type="password">

<input type="radio">

<input type="range">

<input type="reset">

<input type="search">

<input type="submit">

<input type="tel">

<input type="text"> (default value)

<input type="time">

<input type="url">

<input type="week">

[artofinternet]

network applications

middleware is essentially there to help developers address the fallacies of distributed computing

[artofinternet]

HEX for reference

https://www.nicolas-hoffmann.net/utilitaires/codes-hexas-ascii-unicode-utf8-caracteres-usuels.php

[artofinternet]

ERD API and English

In this article, I assume you already have a human-readable specification of a system. The article was put together using information from

1. http://dx.doi.org/10.14257/ijdta.2015.8.2.22

2. https://www.oreilly.com/content/how-to-design-a-restful-api-architecture-from-a-human-language-spec/

3. https://zapier.com/learn/apis/chapter-6-api-design/

4. https://www.sciencedirect.com/science/article/pii/0020025583900142

5. https://www.lucidchart.com/pages/er-diagrams#section_0

6. https://pdfs.semanticscholar.org/6ae2/465cafdb0cbdcc2d247fbbb64438c5bc89c1.pdf

In short, the story goes something like. “You can’t always have a database so in that case you need to use an API call (or ftp or email). The end.”

The assumption for the human readable specification is as follows:

We’re going to design an app for a bike rental service. This service has stations around a city. 

Users can rent a bike using a mobile app. All stations are connected to the same server, as is the app. Stations know when a request to release a bike is made and when a bike is returned to a station. To rent a bike, the user follows these steps:

Before going to a station, the user sees on the app the list of all stations. Each station has a name, a latitude and longitude location, and a numeric identifier. Also, the app shows the quantity of available bikes on each station. This is useful because some stations may not have bikes available for rent, i.e., all have been rented.

The user goes to one of the stations with available bikes.

Once at the station, the user decides which bike they want. Like the stations, each bike has a number.

The user rents a bike by inputting on the app the station number, the available bike number, and the destination station number.

The station releases the chosen bike.

The user rides the bike.

After the ride, the user returns the bike to the destination station they specified.

Besides the bike rental itself, the service has other additional constraints and features:

Each user can only rent one bike at a time.

The user can see the history of their rentals, including the current active rental (if one exists). The history of rentals includes rental start dates and end dates.

After a rental, the user can change the destination station through the app. However, this change is allowed only during the first 10 minutes after the rent.

The user can also cancel the current active rental within 10 minutes. After canceling, the user must return the bike to the same station it was taken from.

Remember: we’ll just design the mobile app of this bike rental service. We won’t worry about the communication between the server and the stations. Also, we’ll assume all users already have accounts and subscriptions for the service. In other words, we won’t care about user management or payment.

Both Entity relationship modelling and API design follow basic rules around nouns and verbs.

Step 1: Identify Nouns and Verbs (note: assign meaningful relationships between nouns)

By reading the spec, we can get the following list of nouns and verbs related to the system use cases:

Nouns:

City

User

Station

Bike

Verbs:

View (user views the list of stations)

Rent (user rents a bike)

Show (app shows the quantity of available bikes at a station)

Release (station releases a bike)

Ride (user rides a bike)

Return (user returns a bike)

View (user views the history of rents)

Change (user changes destination station)

Cancel (user cancels the active rent)

For ERD follow these rules.

Design a conceptual schema by creating an ER diagram. (a) Identify entity types.  Assign a singular noun to each entity type. (b) Identify relationships between (among) entities.  Use a meaningful verb for a relationship name. (c) Draw an ERD without attributes. (d) Identify relationship cardinalities. • Mapping constraint (1:1, 1:N, N:M) • Participation constraint (Total, Partial) (e) Assign attributes to entity types and relationship types.  Usually attributes come from nouns, adjectives or adverbs. (f) Select identifiers (primary keys) for entity types. • Weak entity: composite primary key. • Regular entity: choose/create a single attribute primary key. (g) Select the PKs of relationships. • If 1:1, then the PK of either side entity type may be selected. • If 1:N, then the PK of N-side entity type must be selected. • If M:N, then a composite PK consisting of PKs of two entity types must be used. • If ternary, then a composite PK consisting of the PKs of at least two entity types. The actual PKs selected will vary depending on the cardinality.

For REST API design

Resources – You can think of those as the “nouns” of your system. For example, in a food-delivery service API, the nouns would be restaurant, menu, menu item, restaurant owner, etc. Those nouns are what hold the State, the “S” in REST.

Representations – Representations are the way API clients see the resources. A RESTful API never hands resources directly to a user. Interactions happen only via representations of the real resource. For example, you can store all the menu items for a restaurant in a database table, but the representations of these items in your API might be a list of names and prices, perhaps filtered to reflect restrictions specified by the user. To do this, we use media types such as JSON and XML. That’s why REST is “RE”presentational.

Actions – Because API clients do not have direct access to resources, they need actions to alter the state of a resource. Those actions are the verbs of our system. They are what “transfer” the state, the “T” of RES

so using our spec we won’t need REST resources for all of those nouns, nor REST actions for all of those verbs. We can remove the following:

City noun. We can assume each user is interested only in the city they’re currently located in.

User noun. We already said we can suppose all users have accounts.

Bike noun. The service doesn’t offer any additional info about bikes, except if they’re available or not.

Release verb. We’re designing the API for the mobile app, not for the station.

Return verb. Same as above.

Ride verb. The service doesn’t care how the user rides the bike.

After removing those, we’ve ended up with this new list:

Nouns:

Station

Verbs:

View (user views the list of stations)

Rent (user rents a bike)

Show (app shows the quantity of available bikes at a station)

View (user views the history of rents)

Change (user changes destination station)

Cancel (user cancels the active rent)

Great, now the list is more realistic to the mobile app API use cases. The next step is to convert the nouns to HTTP resources with URLs and the verbs to HTTP methods.

It’s easy to convert nouns into HTTP resources with URLs. For example, the noun “station” can become a resource located by the URL path /stations/ in our API. But there are some gotchas in the conversion of verbs to HTTP methods. Let’s see why.

A word on HTTP “verbs”

One limitation we have while mapping a spec to a RESTful API is the restricted set of verbs HTTP provides. We can only use the documented HTTP methods: GET, POST, PUT, PATCH, DELETE, etc. As you can see, we don’t have a “RENT” verb, even though at first glance our application requires it.

Instead of custom verbs, we must define custom nouns for our RESTful API. Anything can be a noun. Therefore anything can be a resource that’s mapped by a URL. Even if it doesn’t look like a noun at first sight. “RENT” fits more into a verb, but you can noun-ify it to make it a resource. Think about the “Rent” noun, not the “RENT” verb. Then you’ll see that you can “add a Rent”. And HTTP fits here because it has the POST verb for adding things. See? Just by changing the way we think about noun and verbs we can adapt our application to HTTP. The correct way to rent something via HTTP is to POST a Rent.

Thus, to properly design our RESTful API we need to know really well the meaning of each HTTP method. What are the semantics behind each method? How should we use them? Let’s see:

GET – Should be used to retrieve data from the server. Means “give me a representation of this resource identified by this URL”. It’s worth noting that we must never use GET to change resources. For this, we have the following other methods.

POST – Should be used to provide data to the server. Means “process the resource representation as a new subordinate of this URL”. In practice, POST is mostly used for creating resources. The client specifies the resource representation in the request body and makes a POST to the URL that holds the collection of resources. 3

PUT – Should be used to update existing server resources by replacing their old state with a new one. Means “use this representation to replace the resource identified by this URL”. 4

DELETE – Should be used to remove server resources. Means “delete the resource identified by this URL”.

By following the semantics of each method, we can design a truly RESTful API. Now let’s get back to the next step: converting the nouns to HTTP resources with URLs and the verbs to HTTP methods.

Step 2: Extracting URLs and their methods from nouns and verbs

We’ve seen that mapping nouns to resources is as easy as Station => /stations/. But verbs are different. Some verbs are easily mapped to a HTTP method, because sometimes the semantics match. Other verbs will need to be noun-fied to become resources, as we’ve seen in the last section with “Rent”.

Besides that, we also need to care about which data from resources will be included in request and response bodies. For example, on a POST request for creation, the body needs to include the resource representation to be created. Another example, a GET response body needs to contain a resource representation, but a DELETE response body does not.

Summarizing, here’s what we need to answer here to design our API:

Which HTTP methods map to our verbs?

Which resources and corresponding URLs should we create for our nouns and noun-fied verbs?

For each URL + method, which resource data should be included in the request body?

For each URL + method, which resource data should be included in the response body?

The result of answering those questions is the basis of our RESTful API design: combinations of URLs and the HTTP methods they respond to, along with what’s included in the request and response bodies.

To achieve this, let’s analyze each of our verbs and think about the nouns they interact with:

View (user views the list of stations)

Which HTTP method maps to “View”? “View the list” means the API should show the list. Which HTTP method fits that? The GET method.

What’s the noun here, what’s the resource? Which URL fits this resource? We need a GET request to the list/collection of stations. “Collection of stations” is the resource here. “Station” is already a defined noun. Thus, we should implement a /stations/ URL that accepts GETs.5

What should be passed in the request body? Since we’re only GETting, we don’t need to pass anything.

What should be included in the response body? GET /stations/ needs to return a representation of the collection of stations. This representation could be a JSON list, for example. Each station has a name, a location, and identifier, so we need to include these in the representation. To represent the location, we’ll use a JSON list with the latitude and longitude as floats.

This means we need to have something like:

Request: GET /stations/ Request body: (empty) Response body: [{ "id": 1, "name": "John St", "location": [40.7, -74] }, { "id": 2, "name": "Brooklyn Bridge", "location": [40.7, -73] }]

Rent (user rents a bike)

Which HTTP method maps to “Rent”? What’s the noun here, what’s the resource? Which URL fits this resource? The noun here seems to be “bike”. But if you pay a little more attention, you will notice that this is not about the bike object. Instead, we are actually talking about the bike “rental”—or the act of renting. That’s why we need to noun-ify the “Rent” verb. Remember how in HTTP we use POST for creating resources? So a “Rent” action can be represented as the POSTing of a rent resource representation. This can be done with a /rents/ URL that accepts POSTs.

What should be passed in the request body? The POST request needs to include the station number, the bike number to be rented, and the destination station. These are the parts of the representation of a rent.

What should be included in the response body? Nothing. If the POST succeeds, the API client will know the rent has been made.6

Here’s the practical example:

Request: POST /rents/ Request body: { "origin_station_id": 1, "bike_number": 10, "destination_station_id": 2 } Response body: (empty)

Show (app shows the quantity of available bikes at a station)

Which HTTP method maps to “Show”? Easy, you already know this one: GET.

What’s the noun here, what’s the resource? Which URL fits this resource? The noun is “quantity of available bikes at a station”. But we already have a URL and method that returns info about stations: GET /stations/. Why not just add the number of available bikes to each station in its response? Let’s update GET /stations/.

What should be passed in the request body? Nothing. This is a GET.

What should be included in the response body? We’re working here with GET /stations/. We just need to add the info about the quantity of available bikes at each station.

In practice, this means:

Request: GET /stations/ Request body: (empty) Response body: [{ "id": 1, "name": "John St", "location": [40.7, -74], "available_bikes_quantity": 10 }, { "id": 2, "name": "Brooklyn Bridge", "location": [40.7, -73], "available_bikes_quantity": 2 }]

View (user views the history of rents)

Which HTTP method maps to “View”? GET.

What’s the noun here, what’s the resource? Which URL fits this resource? We already noun-ified “Rent”. We can now use the /rents/ URL to return the collection of user rents. Besides accepting POSTs, this URL can also accept GETs. A GET request can return the history of the rents made by the user.

What should be passed in the request body? Nothing. This is a GET.

What should be included in the response body? The collection of user rents. It’s a good practice to always return an identifier in the representations. It makes easier for API clients to manipulate rents, so let’s return the ID of each rent in the collection. Remember that on the creation of the rent, we pass the origin station, the bike number, and the destination station, so we can include those here too. Also, according to the spec, we need to include the rent’s start date, end date, and some flag indicating whether the rent is the currently active one.

We can do it like this:

Request: GET /rents/ Request body: (empty) Response body: [{ "id": 1, "origin_station_id": 1, "bike_number": 10, "destination_station_id": 2, "start_date": "2017-06-08T19:30:39+00:00", "end_date": null, "is_active": true }]

Change (user changes destination station)

Which HTTP method maps to “Change”? PUT is the method for updates.

What’s the noun here, what’s the resource? Which URL fits this resource? Think what the user is changing the destination station of. Of the active “Rent”! We still don’t have an URL for a single rent, but making one is as easy as: /rents/{id}/. Since GET /rents/ returns the IDs of the user rents and which one is the active one, the mobile app will be able to use that to build the URL of the rent to be changed.

What should be passed in the request body? A representation of what can be updated: the new destination station identifier number.

What should be included in the response body? Nothing. If the PUT succeeds, the API client will know the change has been made.

The example:

Request: PUT /rents/321914/ Request body: { "destination_station_id": 2 } Response body: (empty)

Cancel (user cancels the active rent)

Which HTTP method maps to “Cancel”? Canceling a Rent can be thought as deleting it. DELETE can be used here.

What’s the noun here, what’s the resource? Which URL fits this resource? The active rent is the resource. The URL will be /rents/{id}/, where id is the identifier of the active rent.

What should be passed in the request body? Nothing. The ID contained in the URL is enough to locate the rent to be canceled.

What should be included in the response body? Nothing. If the DELETE succeeds, the API client will know the change has been made.

The example:

Request: DELETE /rents/321914/ Request body: (empty) Response body: (empty)

Phew! After meditating about all the verbs in our spec and deriving new nouns as necessary, we mapped all features of the API for the mobile app. We converted a human-language spec into a list of URLs7 with the HTTP methods they respond to. Also, we know which data those URLs expect on requests and return on responses.

[artofinternet]

Why API

Bringing it all together

I have worked in the field of integration for 20 years and during that time one thing has remained consistent. Developers of traditional applications, some managers and some infrastructure or hardware focused professionals just don’t understand why the field exists or they don’t respect it. Mainly because there are many ways to skin a cat. However I will now attempt to explain it for you here.

One word that describes why integration exists is scope; “hello world” should really be “hello worlds”. One person can not and should not do it ALL. Competition and rivalry is good and well but undermining the need for other people and obfuscating the area between people and systems is just not good business. Keeping things simple and following consistent rules DOES AND SHOULD make sense. 

I will also use a real life scenario below to explain. You have a footy club and you have a footy club application. The footy club application keeps track of players, games, rosters, scores, names of players, wins, losses.

The purpose of the application is for the coach to have reports that analyse play, for players information to be maintained and for players to know where the next game is going to be. However as the scores are kept within the application a report can also be written regarding specific players for historical purposes. 

A trivia games company wishes to use this historical information and rather than providing the games company a log in to your footy club application you provide them with an API that allows them to interrogate the score data set.

http://footyclub.com.au/joeblogs/score?year=2016

http://fottyclub.com.au/teamVSportMelbourne?decade=2010

and so forth.

That is the footy club application can focus on maintaining player information, footy scores etc and the trivia games business can get information regardless of how the footy club maintain their score. Perhaps they would even be willing to pay for that information. So there you have it, the business value of integration, pivoting, APIs and not being reliant on one persons opinion about why something exists.

Whether the information provided to the games company comes in the form of a report, API or  csv file is a design decision and it just impacts how the games company receives the information. APIs calls are more “real time” and CSVs can store large amounts of data that doesn’t change often. That is, it is quite unlikely that you would find out about that goal scored 10 minutes ago from a CSV file extract. 

How your business provides information to others and why is a design decision. Eventually someone makes a decision about which way to design it and that’s the way it is usually implemented. Make it your business to respect your own information and the information you provide others. Integrity should be valued in every meaning of the word. 

[artofinternet]

RAML

Always remember that over engineering is never a good idea. Ever. This you tube tutorial is only 15  minutes and so is this one, but this post (yeah this one) is a brief overview/summary/snippet of the larger spec. Also this book provides step-by-step guidance for designing APIs that “reflect an application's core business value”.

The entire RAML spec is found here. I will now summarise some aspects I consider important from the spec in this blog.

The RAML specification is organized as follows:

Basic Information. How to describe core aspects of the API, such as its name, title, location (or URI), and defaults and how to include supporting documentation for the API.

Data Types. Modeling API data through a streamlined type system that encompasses JSON and XML Schema.

Resources. How to specify API resources and nested resources, as well as URI parameters in any URI templates.

Methods. How to specify the methods on API resources and their request headers, query parameters, and request bodies.

Responses. The specification of API responses, including status codes, media types, response headers, and response bodies.

Resource Types and Traits. The optional use of RAML resource types and traits to characterize resources.

Security. Specifying an API security scheme in RAML.

Annotations. Extending a RAML specification by defining strongly-typed annotations and applying them throughout the specification.

Includes, Libraries, Overlays, and Extensions. How an API definition can consist of externalized definition documents, packaging collections of such definitions into libraries, separating and overlaying layers of metadata on a RAML document, and extending an API specification with additional functionality.

The root section of he RAML document describes the basic information about an API, such as its title and version. The root section also defines assets used elsewhere in the RAML document such as types and traits.

Example RAML spec

#%RAML 1.0 title: Amazon S3 REST API version: 1 baseUri: https://{bucketName}.s3.amazonaws.com baseUriParameters:  bucketName:    description: The name of the bucket

#%RAML 1.0 title: Salesforce Chatter REST API version: v28.0 protocols: [ HTTP, HTTPS ] baseUri: https://na1.salesforce.com/services/data/{version}/chatter

Explicitly defining a mediaType node for a body of an API request or response overrides the default media type, as shown in the following example. The resource /list returns a Person[] body represented as either JSON or XML. The resource /send overrides the default media type by explicitly defining an application/json node. Therefore, the resource /send returns only a JSON-formatted body.

#%RAML 1.0 title: New API mediaType: [ application/json, application/xml ] types:  Person:  Another: /list:  get:    responses:      200:        body: Person[] /send:  post:    body:      application/json:        type: Another

RAML data types

RAML Types in a nutshell:

Types are similar to Java classes.

You can define types that inherit from other types.

Types are split into four families: external, object, array, and scalar.

Types can define two types of members: properties and facets. Both are inherited.

Only object types can declare properties. All types can declare facets.

To specialize a scalar type, you implement facets, giving already defined facets a concrete value.

To specialize an object type, you define properties.

Types borrow additional features from JSON Schema, XSD, and more expressive object oriented languages.

Multiple inheritance is allowed.

Properties are regular, object oriented properties.

Facets are special configurations. You specialize types based on characteristics of facet values. Examples: minLength, maxLength

[artofinternet]

Mulesoft and Firewalls

When a browser makes an HTTP request to a domain (domain name or URL hosted on a web server see this post) and that domain returns a page, that page is the origin domain (and can be uniquely identified by an IP address). Any scripts running in that page are allowed to make additional requests back to the origin domain only. If a script attempts to make a request to or load resources from a different domain, the response is normally blocked to prevent the script from gaining access to other sites you visited. That is the script rendering the page to your browser via HTTP is not normally allowed to have free rein (ie update access) of your computer’s resources let alone operating system (ignoring cpu and ram usage) unless that is intended by functionality (ie save file button).

If your API is located behind a firewall that prevents inbound requests, the API is unreachable. You won’t be able to use API Console, API Designer, or API Notebook unless you use the Anypoint Platform Cross-Origin Resource Sharing (CORS) policy to allow users and/or client requests to access the tools whose resources are located outside your origin domain.

Releasing an API to production without properly addressing a security model to handle cross-origin resources can potentially enable dangerous Cross-Site Request Forgery (CSRF) attacks, among other threats that can harm clients and users accessing your resources. For more information on what Cross-Site Request Forgery is you can watch this you tube tutorial.

The API Manager browser tools (API Console, API Designer, and API Notebook) are hosted on an HTTPS endpoint. All requests and responses sent between your browser and the platform’s servers are encrypted using SSL. In addition, if you’re using the default server-side proxy generated by the tools instead of bypassing the proxy, the proxy makes requests to your API and encrypts the responses through SSL so that they can be displayed in the browser without triggering a mixed content error.

If you’ve disabled the platform’s server-side proxy, any requests to your API are no longer routed through this proxy and are instead made directly to it. This situation isn’t a problem if your API resides at an HTTPS endpoint, because all communication between the browser and the requested resources is encrypted using SSL

Some of the content in this post comes from here. 

I will address the terms, proxy, reverse proxy, firewall and other security terminology and concepts at a later post.

[artofinternet]

API components

Three essential API components are endpoints, methods and parameters.

Endpoinds: a path that uniquely identifies a resource.

Method: http methods (get, post, put, patch, delete). http methods are discussed in an earlier post

Parameters: variable values for distinguishing resources of a particular type or modifying the scope or behaviour of the API request. Parameters can appear in the path of the endpoint, in a query string at the end of the endpoint or in the body of the request (usually restricted by method, see below). These parameters or variables are inevitably used by the function that is mapped to the URL you’ve entered into the browser. This earlier post talks about URL routing tables and mapping them to functions.

-GET path, query (not strictly enforced by the protocol itself and the term ‘parameter’ here is only meant for current singular HTTP synchronous connection (a<>b), not the workflow between people and between different connections. In addition a very popular server product ElasticSearch does use the body on GET)

-POST path, body

-PUT path, body

-PATCH path, body

-DELETE path, body

[artofinternet]

Protocols and HTTP

A protocol (stricter than but can be thought of as etiquette) is a standard set of rules that allow electronic devices to communicate with each other. These rules include what type of data may be transmitted, what commands are used to send and receive data, and how data transfers are confirmed. You can think of a protocol as a spoken language or more accurately the formal etiquette or rules around what/how the language is spoken, what/how it is listened to, what/how and whether it is responded to.

Hypertext Transfer Protocol (HTTP) is an application-layer protocol for transmitting hypermedia documents, such as HTML. It was designed for communication between web browsers and web servers, but it can also be used for other purposes. HTTP follows a classical client-server model, with a client opening a connection to make a request, then waiting until it receives a response. HTTP is a stateless protocol, meaning that the server does not keep any data (state) between two requests. Though often based on a TCP/IP layer, it can be used on any reliable transport layer, that is, a protocol that doesn't lose messages silently like UDP does. RUDP — the reliable update of UDP — is a suitable alternative. As a matter of fact as of July 2020 HTTP/3 which is currently in an Internet-Draft with about 4% of all website using it, uses a type of UDP called QUIC. One of the aims of QUIC is to improving performance on error-prone links, as in most cases considerable additional data may be received before TCP notices a packet is missing or broken, and all of this data is blocked or even flushed while the error is corrected. In QUIC, this data is free to be processed while the single multiplexed stream is repaired.

The HTTP protocol has methods that define the operations that can be performed.

GET retrieves the current state of a resource in some representation usually XML or JSON, POST create a new resource of a type, or adds a new resource to the collection. This method generally requires additional parameters. DELETE remove a resource or disassociates one resource from another.  PUT replace a resource completely or associates one resource with another, if the resource doesn’t exist a new one is created, PATCH partially updates a resource (only submitted data is updated) or modifies a resource. The body of the request contains the new resource representation.

[artofinternet]

Mule events

The Mule event is an object structure that gets generated at the source and passed between the processors.

The mule message gets populated with the data and metadata that is passed with the application trigger and the variables are created and managed by the processors within the flow.

For example if the Mule application is triggered by an HTTP request the attributes will be populated with the HTTP request attributes including things like the headers, query parameter, uri parameters and the method. If the method is POST, PUT or PATCH the payload will be populated with the body of the HTTP request.

[artofinternet]

API Lifecycle

Roughly is: Specify -> Build -> Deploy

Your API shoul dbe decoupled from your application and technology stack. The API should not change if your application changes from Java to Php.

API Specs can be designed using new technologies/tools.

- RAML (designed as a modeling language, based on YAML to focus on design)

- IO Docs  (documenting your API)

- Swagger (design first)

-  API Blueprint (documentation focused)