The URL basics

URI is short-cut for Uniform Resource Locator and is part of URI (Uniform Resource Identifier). It is formed from several parts.

protocol://sub-domain.domain.TLD/query#fragment

Lets talk over meaning of each of them in relation to AsynCode Framework.

• protocol - it's always HTTP or HTTPS
• sub-domain - along with domain and TLD, refers to exact location of application installation; can be empty; can be used to divide project into several parts or as short-cut of other, mostly longer, URLs
• domain.TLD - unique name of the application or application set
• query - string parsed by application internals; most important part described in separate chapter; can have "/" signs
• #fragment - part used by browser; not important for server part of application

The sub-domain.domain.TLD can be replaced by computer IP. Length of URL shouldn't be longer than 1400 characters (there is no need for sending more packets than one and typical packet is 1500 bytes long, headers can take up to 60 bytes, but for safeness we take 1400 as maximum).

After application of ACF specific rules, the URL is simplified to HTTP[S]://subdomain.domain.TLD/query. We will focus on query part.

The query

The query part of URL is most important for ACF. It contains information about request characteristics. There are following rules of good queries:

1. understandable to humans - should be similar to sentence, tell the location on site or something of equal memorable and useful information
2. SEO compatible - same rules as above
3. for framework engine:
   • meaningful - should hint the engine how to handle request
   • easy to implement
   • easy to parse - it should be extremely fast
   • should contain data to handle request
4. there should be one standard across all applications

In several meetings and self-research it has been settled that there is no way to achieve all these goals in simple query part of URL. Therefore, there was developed alternative solution based on XML. Within query part of URL achieved, with some exceptions, goals 1, 2 and 4. Within XML are keeping detailed description of URL meaning.

The structure of query is:

/view/data/human-readable-part

where:

• view is a phrase associated with XML file (should be one-word phrase, but we allow all but '/' signs, because of namespaces e.g. for distinguishing system views which are used only by admins from user views)
• data is as human-readable as possible and consist of N slash-separated values
• human-readable-part is not necessarily important data for engine, but IS VERY important for search engines and humans; It might also be the way to create application logic in HTML.

Example of whole URL:

http://app.example.com/text/1/2000-01-01/The-Article/

Where view is text and it provides text with id contained in first (and only) parameter - here it is "1". "2000-01-01" is date of creation or modification and "The-Article" is a title of article. You can look at the path as function call where only first N parameters are meaningful and rest is silently dropped.

The view designing rules

It is application developer work to make a list of views which should be in a project and give them appropriate names. View is definition of one URL schema. Beside extending URL with additional information, view is the only one file needed to tell ACF what actions under what conditions it should perform and how to output data. Here are some URL issues:

1. There are no information about attribute name associated with data in URL's query section. The order of parameters is meaningful.
2. The number of parameters cannot be variable - there is no delimiter after the data part - use another view to handle different sets of parameters
3. There is type checking system for each value which can be used but it's not obligatory
4. There is a way to send arrays in query by using "_" character e.g. list of numbers /1.2_3_10/ or list of strings /first-string_second-string/ - NOT IMPLEMENTED YET, implementation upon request

Beside these constraints this is still very powerful approach with only one disadvantage in comparison to full URL standard. It's enforcement to paying attention at the order of parameters and their quantity. Developer with programming background must assume the path as call of function which can't handle variable quantity of parameters (the order is common issue of functions).

Explanation: Above rules are very controversial and hard to follow, but there are factors that forces us to do so. The most important here is SEO compatibility. It prevent us from using any other characters than a-z, A-Z, 0-9, -, _ and /. It is most important factor for client to have site with links understandable by search engines. He or she have great financial benefits from it and don't care about implementation issues. It's also important to have pretty looking links that users will understand - after all, we are developing applications for them not for us!

The definitions in XML

Every view of application is associated with XML file residing in server in special directory (can be virtual). These files, described in detail in "AsynCode Framework episode 3", contain definitions of each view. The definition of view is a list of actions that engine should execute. It can be request for data (like in example with text), request for computation (e.g. what day of week was on 1 January), addition or update of data (e.g. "last seen" feature), things related to session management etc.

View description XML contains information part about parameters: number of them, types and assignments to names. There is also declaration of actions which uses the data from URL, POST and internal structures to dynamically fill fields with data and push it to execution.