ShiftInsert.nl

Coldbox and VueJS untangled

Tag: REST API

Problem Details for HTTP APIs: Modifying your Coldbox REST handler response

February 2, 2021 / / 2 Comments

Coldbox had a base handler and response for RESTful services for many years. Initially this was added in application templates but in version 6 this functionality was added to the core. The base handler wraps around your own actions and provides a lot of automatic errorhandling, addition of some development headers and some global headers. By using the default event.getResponse() response (available as prc.response in previous versions) it provides a default response format which looks like this:

{
    "data": {
        "name": "someData"
        "id": "98765",
        "name": "provMan"
    },
    "error": false,
    "pagination": {
         "totalPages": 1,
         "maxRows": 0,
         "offset": 0,
         "page": 1,
         "totalRecords": 0
    },
    "messages": []
}

That’s a lot of different keys for a default response format. The data field makes sense most of the time, and the pagination key (which is new in cb6) can be handy but we don’t use it (yet). The error and messages keys are less useful to us. Let me explain why first, and then I will explain how to modify your responses in coldbox 6.

Continue reading

Customize your resource routing in Coldbox

December 22, 2020 / / 0 Comments

In this post I will show you how coldbox can help you creating resourceful routes, how cbswagger shows me that I don’t want the defaults resource() routing method, and how easy it is to create your own method!

If you want to create a REST API in coldbox, you often need to create a lot of routes for this API. So let’s say you want to create endpoints to list, view, update, create and delete a User resource. Following the coldbox manual, I need to implement the following routes:

Continue reading

Internationalization (i18n) in a ColdBox REST API

May 16, 2019 / / 0 Comments

When developing a ColdBox REST API we wanted to add multilingual capacities. Coldbox has a nice module cbi18n for this.  When you set a new locale using

i18n.setfwLocale(newLocale);

this locale will usually be saved in a cookie and sent back with every request. But for our REST API we are looking for a more standard way of content-negotiation. We want to set an Accept-language header on every request and return a Content-Language header for one of our supported languages. The Accept-language can contain multiple choices, and each choice can have language, country and a q factor which specifies a preference. Example: 

Accept-Language: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5

In our case we are only serving two languages, English (en) and Dutch (nl) which is the default if no header is specified. So, in our header we need to find out which language (nl, en or something else) is requested and if it is not Dutch (nl) we serve English. In a later stage we might add German for some customers but for now these two languages are sufficient.

Coldbox interceptors are the perfect vehicle for this kind of logic. We define a LanguageInterceptor which has the following code:

// Language interceptor
component{
	property name = "i18n"				inject="i18n@cbi18n";
	
	void function configure(){
	}

	function preProcess( event, interceptData, buffer, rc, prc ) {
		var languageHeader =event.getHTTPHeader( "Accept-Language", "nl" );
		// get first language from comma separated list
		//cleanup for potential ;q weighting factor
		//plus cleanup for potential - dash separator
		var firstLanguage = listFirst(listFirst(listFirst(languageHeader),";"),"-");
		var newLocale = ( firstLanguage == "nl") ? "nl_NL" : "en_US";
		var contentLanguage = ( firstLanguage == 'nl') ? "nl-NL" : "en-US";
		i18n.setfwLocale(newLocale);
		event.setHTTPHeader( name = "Content-Language", value = contentLanguage );
	}
}

As you can see from the listfirst/listfirst/listfirst line, there is some parsing involved, because there might be multiple language entries separated by a comma. Each of these entries could have a q factor appended (after a ; character) and finally there might be a country designation after a –. So finally we end up with nl, en or something else. Coldfusion locales are formattet as nl_NL or en_US for example, and in the Content Language returned everything should be formatted with a dash instead of an underscore.

Finally, don’t forget to register your interceptor in Coldbox.cfc or your ModuleConfig.cfc!

© 2024 ShiftInsert.nl

Theme by Anders Noren — Up ↑