Docs
ServoyCloudSupportSamplesOpen SourceCommunity
  • Home
  • GUIDES
    • Platform Overview
    • Get Servoy
    • Get Started
      • Chapter 0
      • Chapter 1
      • Chapter 2
      • Chapter 3
      • Chapter 4
      • Chapter 5
    • Get Help
      • SuLA Instructions
      • SuLA Terms
    • Develop
      • Application Design
        • Forms
          • Layout Management
            • Simple Layout
            • Fully Responsive
              • Bootstrap 12-Grid
              • Flexbox
              • Custom Div
              • Collapsible Container
              • Simple Collapsible
              • Center Container
              • Inline Group Container
            • Abstract Form
          • Form Containers
            • Form Container
            • Tab Panel
            • Split Pane
            • Collapse
            • Accordion Panel
            • Form Component
            • List Form Component
          • Form Inheritance
          • Form Components
        • UI Components
          • Buttons and Text
            • Badge
            • Button
            • Data Label
            • Dropdown
            • Image
            • Label
          • Grids
            • Data Grid
            • Power Grid
            • Table
          • Input Controls
            • Calendar
            • Calendar Inline
            • Checkbox
            • Choice Group
            • Combobox
            • Group Buttons
            • Html Area
            • Input Group
            • Rating
            • Slider
            • Switch
            • Spinner
            • TextArea
            • Textbox
            • TextBoxGroup
            • Type Ahead
            • select2tokenizer
          • Media
            • Carousel
            • Embedded YouTube
            • File upload
            • Image label
            • Lightbox Gallery
            • MultiFile Upload
            • PDF JS Viewer
            • PDF Viewer
          • Mobile
            • Native Data List
            • Native Select
          • Navigation
            • Breadcrumbs
            • Navbar
            • sidenav
          • Visualization
            • DBTreeview
            • Progress Bar
            • Treeview
            • ChartJS
              • Data Labels Plugin
              • Funnel Chart
              • OutLabels Plugin
              • TreeMap
          • Specialized Components
            • Smart Document Editor
            • Servoy PDF Viewer
            • Fullcalendar Component
              • Fullcalendar
              • Fullcalendar Events
              • Migrating calendar from Smart and Web client to NG client
            • Fullcalendar Component 2
            • Canvas
            • Google Charts
            • Google Maps
            • svySignature
            • svywebcam
        • Styling and Themes
          • Default Theme Properties
          • CSS / LESS
          • Component Variants
          • Font Icons
        • Data Modeling
          • Databases
            • Tables
              • Columns
              • Calculations
              • Aggregations
              • Methods
              • Events / Triggers
              • Table security
            • Views
            • Procedures
          • Relations
          • Value Lists
          • Menus
          • In-Memory Databases
          • View Datasource
        • Modular Design
      • Programming Guide
        • Scripting the UI
          • Scripting Forms
          • Interacting with Components
          • Navigation
          • Windows, Dialogs and Popups
          • Events Manager
        • Working with Data
          • Concepts
          • Loading
          • Sorting
          • Iterating
          • Searching
            • Find mode
            • Query Builder
            • SQL String
          • Filtering
          • Editing
          • Validation
        • Automation and Scheduling
          • Batch Processor
          • Headless API
          • Scheduler API
        • Creating REST APIs
        • Consuming Webservices
        • Working with Files
          • File Plugin Basics
          • Images
          • Excel
          • PDF
          • JSON
        • Browser Utilities
          • Notifications
            • Web Notifications (Toastr)
            • Web Notifications (Native)
            • Block UI
          • Session Management
          • Keyboard Utilities
          • NG Utils
        • Sending and Receiving Email
        • Servoy Jasper Reports
          • Input Type
          • Display Mode
          • Output format
          • Jaspe Reports Viewer
        • Extensions
          • Modules
            • svyPhonegap
              • First Use Guide
              • Barcode Scanner
              • Browser
              • Camera
              • File
              • Fingerprint
              • Location
              • Network Interface
              • Phonegap
              • Printer
              • Push Notifications
            • svyAPI
              • Getting Started
            • svyLookup
              • Custom Templates
              • API Documentation
              • svyLookup v1
                • API Documentation v1.0.0
                • Base Form svyLookupTable v1.0.0
                • Base Form AbstractLookup v1.0.0
            • svyNavigation
              • API Documentation
                • API svyNavigation
                • API svyNavigationHistory
                • API svyNavigationUX
            • svyPopupFilter
              • Simple Filter Pickers
              • Custom Templates
              • API Documentation
                • API svyToolbarFilter
                • API svyPopupFilter
              • API Documentation v1
                • API svyToolbarFilter v1
                • API svyPopupFilter v1
            • svySearch
            • svySecurity
              • Overview
              • Token-based Auth and SSO (NEW!)
              • API Documentation
              • Getting Started
              • Tenant replication
              • Security Management Console
                • Classic Security Management Console
              • svySecurityUX
              • svyProperties
              • API Doc svyProperties
            • svyUtils
              • Log Manager
              • Log Manager Appenders
              • Smart Doc Editor Utils
              • Custom Dialogs
              • Excel Utils
                • Full API Reference
              • Crypto Utils
      • Security
        • Authentication
        • Permissions
          • UI Permissions
          • Data Permissions
          • Runtime Permissions
        • Audit Logging
        • OAuth
        • JWT
      • Multi-Language Support
      • Mobile Development
        • Getting Started
        • Mobile Design
        • Native Mobile Integrations
        • Building a Native Binary for the App Store
      • Native Desktop Development
        • NGDesktop UI plugin
        • NGDesktop Utils
        • NGDesktop File Plugin
    • Deploy
      • WAR Deployment
      • Docker Deployment
      • Server Configuration
        • Server Settings
        • Server Plugins
        • Database Servers
          • Locks
          • Transactions
          • Oracle
          • SQLServer
        • Client Sessions
        • Batch Processors
        • License Management
        • Monitoring
          • Server Log
          • Browser Console Log
          • Websocket Log
          • Query Performance
          • Client Performance
          • Client Event Tracing
          • Monitoring Servoy with JMX
      • NGClient deployment
      • Troubleshooting
      • Other Topics
        • Security: Cross-site Scripting
        • Running in an iFrame
    • Extend
    • Contribute
  • Reference
    • Servoy Core
      • Object Model
        • Database Server
          • Table
            • Column
            • Calculation
            • Method
            • Aggregation
          • View
          • Procedure
        • Solution
          • Form
          • Form Component
          • Relation
          • Relation Item
          • Table Node
          • Value List
          • Menu
          • Menu item
          • In-Memory Data Source
          • View Foundset Data Source
          • Variable
          • Column Info
          • Media
          • Layout Container
          • Method
        • i18n Message Key
      • Developer API
        • Globals
        • Forms
          • RuntimeForm
            • controller
            • containers
              • RuntimeContainer
            • elements
              • Component
              • RuntimeAccordionPanel
              • RuntimeBean
              • RuntimeButton
              • RuntimeCalendar
              • RuntimeCheck
              • RuntimeCombobox
              • RuntimeComponent
              • RuntimeDataButton
              • RuntimeDataLabel
              • RuntimeGroup
              • RuntimeHtmlArea
              • RuntimeImageMedia
              • RuntimeInsetList
              • RuntimeLabel
              • RuntimeListBox
              • RuntimePassword
              • RuntimePortal
              • RuntimeRadio
              • RuntimeChecks
              • RuntimeRadios
              • RuntimeRectangle
              • RuntimeRtfArea
              • RuntimeSpinner
              • RuntimeSplitPane
              • RuntimeTabPanel
              • RuntimeTextArea
              • RuntimeTextField
              • RuntimeWebComponent
        • JS Lib
          • Array
          • BigInt
          • Boolean
          • Date
          • Function
          • IterableValue
          • Iterator
          • JSON
          • Map
          • Set
          • Math
          • Namespace
          • Number
          • Object
          • Promise
          • QName
          • RegExp
          • Special Operators
          • Statements
          • String
          • XML
          • XMLList
        • Application
          • APPLICATION_TYPES
          • CLIENTDESIGN
          • DRAGNDROP
          • ELEMENT_TYPES
          • LOGGINGLEVEL
          • NGCONSTANTS
          • UICONSTANTS
          • CSSPosition
          • JSDimension
          • JSDNDEvent
          • JSEvent
          • JSLogger
          • JSLogBuilder
          • JSPoint
          • JSUpload
          • JSWindow
          • JSBounds
          • Renderable
          • UUID
        • SolutionModel
          • ALIGNMENT
          • ANCHOR
          • BEVELTYPE
          • CURSOR
          • DEFAULTS
          • FONTSTYLE
          • MEDIAOPTION
          • PAGEORIENTATION
          • PRINTSLIDING
          • SCROLLBAR
          • TITLEJUSTIFICATION
          • TITLEPOSITION
          • UNITS
          • JSBean
          • JSButton
          • JSCalculation
          • JSComponent
          • JSDataSourceNode
          • JSField
          • JSForm
          • JSLabel
          • JSMedia
          • JSMethod
          • JSPart
          • JSPortal
          • JSRelation
          • JSRelationItem
          • JSStyle
          • JSTab
          • JSTabPanel
          • JSValueList
          • JSVariable
          • JSTitle
          • JSChecks
          • JSCombobox
          • JSHeader
          • JSInsetList
          • JSList
          • JSPassword
          • JSRadios
          • JSText
          • JSTextArea
          • JSWebComponent
          • JSLayoutContainer
        • Database Manager
          • QUERY_COLUMN_TYPES
          • SQL_ACTION_TYPES
          • JSColumn
          • JSDataSet
          • JSBaseRecord
          • JSBaseSqlRecord
          • JSBaseFoundset
          • JSBaseSQLFoundset
          • JSFoundSet
          • JSFoundSetUpdater
          • JSRecord
          • JSRecordMarker
          • JSRecordMarkers
          • JSTable
          • JSTableFilter
          • MenuFoundSet
          • MenuItemRecord
          • QBAggregate
          • QBAggregates
          • QBCase
          • QBCaseWhen
          • QBColumn
          • QBColumns
          • QBCondition
          • QBFunction
          • QBFunctions
          • QBGroupBy
          • QBJoin
          • QBJoins
          • QBLogicalCondition
          • QBParameter
          • QBParameters
          • QBPart
          • QBResult
          • QBSearchedCaseExpression
          • QBSelect
          • QBSort
          • QBSorts
          • QBTableClause
          • QBWhereCondition
          • ViewFoundSet
          • ViewRecord
        • Events Manager
          • EVENTS_AGGREGATION_TYPES
          • EventType
        • Menus
          • JSMenu
          • JSMenuItem
        • JSMenuDatasource
        • Utils
        • Client Utils
          • JSBlobLoaderBuilder
        • History
        • Security
        • i18n
        • ServoyException
          • DataException
        • JSUnit
        • Datasources
          • DBDataSource
          • DBDataSourceServer
          • JSConnectionDefinition
          • JSDataSource
          • MemDataSource
          • MenuDataSource
          • SPDataSource
          • SPDataSourceServer
          • ViewDataSource
        • JSViewDatasource
        • servoyDeveloper
        • enum
    • Extensions
      • UI Components
        • Buttons and Text
          • Badge
          • Button
          • Data Label
          • Drop Down
          • Image
          • Label
        • Form Containers
          • Accordion Panel
          • Collapse
          • Form Container
          • Form Component Container
          • List Form Component
          • Default Loading Indicator
          • Error Bean
          • Portal
          • Responsive Container
          • Servoy Default Navigator
          • Slider
          • Split Pane
          • TabPanel
        • Grids
          • Data Grid
          • Power Grid
          • Table
        • Input Controls
          • Calendar
          • Calendar Inline
          • Checkbox
          • Choice Group
          • Combobox
          • Floatinglabel Calendar
          • Floatinglabel Combobox
          • Floatinglabel Textarea
          • Floatinglabel Textbox
          • Floatinglabel Type Ahead
          • Group Buttons
          • Html Area
          • Input Group
          • Rating
          • Select2tokenizer
          • Slider
          • Spinner
          • Switch
          • TextArea
          • TextBox
          • TextBox Group
          • Type Ahead
        • Media
          • Carousel
          • Embedded YouTube
          • File upload
          • Image label
          • Lightbox Gallery
          • MultiFile Upload
          • PDF JS Viewer
          • PDF Viewer
        • Mobile
          • Native Data List
          • Native Select
        • Navigation
          • Breadcrumbs
          • Navbar
          • sidenav
        • SmartDocEditor
          • Smart Document Editor
        • Visualization
          • Canvas
          • Chart
          • Custom List
          • DBTreeview
          • Foundset List
          • Fullcalendar
          • Gauge
          • Google Maps
          • Kanban
          • Progress Bar
          • Treeview
      • Server Plugins
        • amortization
          • AmortizationCalculation
          • Polynomial
        • clientmanager
          • Broadcaster
          • JSClientInformation (cm)
        • excelxport
        • file
          • JSFile
          • JSProgressMonitor
        • headlessclient
          • JSClient
        • http
          • HTTP_STATUS
          • Cookie
          • DeleteRequest
          • GetRequest
          • HeadRequest
          • HttpClient
          • HttpClientConfig
          • OptionsRequest
          • PostRequest
          • PutRequest
          • Response
          • TraceRequest
          • PatchRequest
          • JSFileUpload
        • images
          • JSImage
        • jwt
          • Algorithm
          • Builder
          • JWTClaims
        • mail
          • Attachment
          • MailMessage
        • maintenance
          • JSClientInformation
          • JSColumnObject
          • JSServer
          • JSTableObject
        • mobileservice
          • OfflineDataDescription
        • oauth
          • ClientAuthentication
          • CustomApiBuilder
          • OAuthProviders
          • OAuthRequest
          • OAuthResponse
          • OAuthResponseBinary
          • OAuthResponseJSON
          • OAuthResponseText
          • OAuthService
          • OAuthServiceBuilder
          • OAuthTokenExtractors
          • RequestType
        • pdf_output
        • rawSQL
        • RestWs plugin
        • rest_ws
          • WsContents
          • WsCookie
          • WsRequest
          • WsResponse
        • scheduler
        • serialize
        • textxport
          • DataProviderExport
          • TabExporter
        • udp
          • JSPacket
        • XmlReader
          • XmlNode
      • Browser Plugins
        • Block UI
        • Block UI (ref)
        • Dialogs Plugin
        • Idle
        • Idle (ref)
        • Key Listener
        • Key Listener (ref)
        • NGDesktop File
        • NGDesktop File (ref)
        • NGDesktop UI (ref)
        • NGDesktop Utils (ref)
        • NG Utils (ref)
        • Office Javascript API for Servoy
        • Phonegap
        • Web Notifications (Native)
        • Web Notifications (Toastr)
        • Window Plugin
        • Font Awesome
      • Modules
        • Smart Doc Editor Utils
        • svyAPI
          • Getting Started
        • svyLookup
          • Custom Templates
          • API Documentation
          • svyLookup v1
            • API Documentation v1.0.0
            • Base Form svyLookupTable v1.0.0
            • Base Form AbstractLookup v1.0.0
        • svyLookupExample
        • svyNavigation
          • API Documentation
            • API svyNavigation
            • API svyNavigationHistory
            • API svyNavigationUX
        • svyNavigationUX
        • svyNavigationUXSample
        • svyPopupFilter
          • Simple Filter Pickers
          • Custom Templates
          • API Documentation
            • API svyToolbarFilter
            • API svyPopupFilter
          • API Documentation v1
            • API svyToolbarFilter v1
            • API svyPopupFilter v1
        • svyProperties
        • svySearch
        • svySecurity
          • Overview
          • Token-based Auth and SSO (NEW!)
          • API Documentation
          • Getting Started
          • Tenant replication
          • Security Management Console
            • Classic Security Management Console
          • svySecurityUX
          • svyProperties
          • API Doc svyProperties
        • svySecurityConsole
        • svySecurityUX
        • svyUtils
          • Log Manager
          • Log Manager Appenders
          • Smart Doc Editor Utils
          • Custom Dialogs
          • Excel Utils
          • Full API Reference
          • Crypto Utils
        • svyUtils$Excel
        • svyUtils$NGClient
        • svyUtils$customDialogs
        • svyUtils$logManagerAppenders
        • svyUtils$tableGrid
      • Layout
        • Boostrap 12grid layout
          • Collapsible Container
          • Simple Collapsible
          • Center Container
          • Inline Group Container
          • Flexbox Layout
      • Solutions
        • Sample Application
          • Tutorial Part 1
          • Tutorial Part 2
      • Packages
        • UI Component Packages
          • Advanced Renderers
          • Bootstrap Components
          • Bootstrap Extra Components
          • Canvas
          • Chart JS
          • Fullcalendar Component
          • googlemaps
          • kanban
          • Servoy Core
          • Servoy Extra Components
          • Servoy NG-Grids
          • Servoy PDF Viewer
          • smartDocumentEditor
        • Browser Plugin Packages
          • Block UI
          • Core NG only Services
          • Key Listener
          • NGDesktop File
          • NGDesktop UI
          • NGDesktop Utils
          • Web Notifications
          • Idle Web Service
    • Servoy Developer
      • Menu
        • File
        • Edit
        • Source
        • Refactor
        • Navigate
        • Search
        • Project
        • Actions
        • Run
        • Window
        • Help
      • Toolbar
      • Solution Explorer
        • Resources
          • Database Servers
            • Database Server
              • Procedures
              • Tables
              • Views
          • Security
          • i18n
        • All Solutions
          • Solution
          • Active Solution
            • Scopes
              • Scope
                • Variables
            • Forms
              • Working Set
              • Form
                • Controller
                • Variables
                • Elements
                • Relations
            • Form Components
              • Form Component
            • Relations
              • Relation
            • ValueLists
              • ValueList
            • Menus
              • Menu
                • MenuItem
            • Media
              • Folder
              • File
            • DataSources
              • In Memory DataSources
                • In Memory DataSource
              • View Foundsets DataSources
                • View Foundset DataSources
            • Servoy Packages
              • Package
            • Modules
              • Module
        • Solution Explorer Contextual List
      • Views
        • Command Console
        • Console
        • Problems
        • Tasks
        • Bookmarks
        • Search
        • Form Hierarchy
        • Help
        • JUnit
        • Outline
        • Profiler
        • Properties
        • Project Explorer
        • Call Hierarchy
      • Editors and Wizards
        • Property configurator for columns
        • Relation Editor
        • Text Format Editor
        • Date Format Editor
        • Number Format Editor
        • Database Synchronization Wizard
        • Security Editor
        • SQL Editor
        • i18n Editor
        • File Import Wizard
        • File Export Wizard
        • WAR Export Wizard
        • NGDesktop Export Wizard
        • Table Editor
        • Metadata Synchronization Wizard
        • Database Server Connection Editor
        • Text Property Editor
        • Valuelist Editor
        • Form Editor
          • Parts of the Form Editor
          • Designing a Form
          • Layout Tools
          • Using Containers
          • Creating and Using Forms
          • Using Servoy Beans
          • Using Shapes
          • Form Editor Subtabs
          • [Tips and Shortcuts][reference/servoy-developer/object-editors/form-editor-tips_and_shortcuts.md]
          • Editong a Responsive LayoutForm
          • CSS Positioning
        • Form Hierarchy
        • Component Properties Editor
        • Variable Editor
        • Method Selection Wizard
        • New Solution Wizard
        • Application Event Types Editor
        • New Form Wizard
        • Form Dataproviders Configurator
        • Servoy Resource Locator
        • Datasource Selection Wizard
        • Sorting Fields Wizard
        • Scripting Editor
          • Getting Started-Overview of Script Editor
          • Code Writing Features
          • Code Navigation
          • Code Rewriting Tools
          • Refactoring
          • Code Formatting
          • Script Editor Tips and Shortcuts
          • Unit Tests
        • Theme Editor
          • General Properties
          • Sidenav Properties
          • Navbar Properties
          • Tabs Properties
          • Windows Properties
          • Dialogs Properties
          • Tables Properties
          • Breadcrumb specific style Properties
          • Brand colors Properties
          • Validations Properties
          • Margins and Padding Properties
        • Editor Selection
        • Run Configurations
        • Debug Configurations
        • Externalize Strings Wizard
        • Font Chooser Wizard
        • Color Chooser Wizard
        • Project Properties Configurator
        • Move Wizard
        • External Tools Configurations
        • About Servoy Developer
        • Servoy Developer Installation Details
        • Eclipse Marketplace Wizard
        • Install Available Software Wizard
        • Cheat Sheet Selection Wizard
        • Servoy Developer Help Wizard
        • Switch to Editor Wizard
        • Find Actions Wizard
        • Customize Perspective Configurator
        • Quick Search Wizard
        • Search Wizard
        • Encoding Wizard
        • Task Wizard
        • Find - Replace Wizard
        • Properties Editor
        • New Project Wizard
        • New Method Wizard
        • New Menu Wizard
          • New MenuItem Wizard
        • Menu Editor
        • ServoyMenu Selection Wizard
        • JSMenu compatible component selector
        • Permissions Configuration Dialog
      • Project File Structure
        • Servoy Installation Directory
          • servoy.properties
        • Workspace Folder
          • Resources Directory
            • Database Information (.dbi) Files
          • Solution Folder
      • Package Manager
      • Preferences
      • Property Types for components / services
      • Debugger
        • Debug Explorer
        • Breakpoints
          • Breakpoint Properties
        • Variables
        • Expressions
        • Interactive Console
    • Application Server
    • Servoy Cloud
      • Cloud Control Center
        • Home
          • Setup Namespace
          • User profile
            • My Profile
            • Support
        • Download IDE
        • Application Overview
          • Applications
            • Pipelines
              • Jobs
                • Packages
                  • Commits
                  • Artifacts
                  • Configuration
                  • Quality reports
                  • Build markers
                • Job Configuration
                  • Build and Deploy or Build
                  • Mobile
                  • Desktop
            • Environments
              • Metrics
                • Users
                • Databases
                  • Metrics
                • System Health
                • Log Activity
                • App performance
                • Query performance
              • Cloud reporting
            • Security
              • Permissions
              • Tenants
            • Reports
            • Security Login Designer
              • Single Sign-On
                • Sign in with Google
                • Sign in with Microsoft
          • Code Repositories
        • Project Management
          • Tickets
          • Backlog
          • Active Sprints
        • User Management
          • Users
          • Roles
        • Administration
          • Security
            • ServoyCloud Roles
          • Credentials
          • Settings
        • Add-Ons
      • Database Backup
      • E2E Cypress Testing
        • Using Cypress
      • On-Premise Deployment
      • Privacy policy (ServoyAI)
      • FAQ
      • Migrate to Servoy Cloud
    • Extensions Developement
      • Component and Services
        • Component Development
        • Service Development
        • Tools and Dev Tips to use for Component/Service developement
        • Manifest (.mf file)
        • Specification (.spec file)
          • Property Types
            • Array property types
            • Custom object property types
            • Findmode property type
            • Foundset property type
            • Tags
        • Directives And Filters
          • Sablotabsequence
        • Console (serverside)
        • ServoyApi (serverside)
      • Serverside Plugins
        • Data Convertors and Validators
        • UI Convertors
  • Release notes
    • Release notes
      • 2025.03
      • 2024.03 (LTS)
      • 2023.03 (LTS)
      • 2025.03 (Servoy Cloud)
      • 2024.12
      • 2024.12 (Servoy Cloud)
      • 2024.09
      • 2024.09 (Servoy Cloud)
      • 2024.06
      • 2024.06 (Servoy Cloud)
      • 2024.03 (Servoy Cloud)
      • 2023.12
      • 2023.12 (Servoy Cloud)
      • 2023.09
      • 2023.09 (Servoy Cloud)
      • 2023.06
      • 2022.03 (LTS)
      • 2022.12 What's new
      • 2022.12
      • 2022.09 What's new
      • 2022.09
      • 2022.06 What's new
      • 2022.06
      • 2021.03.3 (LTS)
Powered by GitBook
On this page
  • Creating REST APIs
  • About RESTful Web Services
  • Implementing a RESTful Web Service in Servoy
  • Supporting GET Requests
  • Supporting POST Requests
  • Supporting DELETE Requests
  • Supporting PUT Requests
  • Supporting PATCH Requests
  • Additional arguments - when adding Extra Data to the Request URL or return values in ws_authenticate
  • Supported Content Types & Encoding
  • Authentication/Authorization
  • JSONP support
  • Versioning support
  • Nested call support
  • Pool of Clients
  • Client plugin
  • Sample Solution
  • More information on RESTful Web Services

Was this helpful?

  1. GUIDES
  2. Develop
  3. Programming Guide

Creating REST APIs

Creating REST APIs

About RESTful Web Services

RESTful Web Services utilize the features of the HTTP Protocol to provide the API of the Web Service. For example, it uses the HTTP Request Types to indicate the type of operation:

Operation
HTTP Request Type

GET

Retrieving of existing records

POST

Creating new records

DELETE

Removing records

PUT

Updating existing records

PATCH

Partially updating existing records

Using these 5 HTTP Request Types a RESTful API mimics the CRUD operations (Create, Read, Update(2) & Delete) common in transactional systems.

A defining feature of REST is that it is stateless: each call to a RESTful Web Service is completely stand-alone: it has no knowledge of previous requests.

Implementing a RESTful Web Service in Servoy

A RESTful Web Service endpoint is created by defining a Form in a Solution and implementing one or more of the following methods to the Form:

HTTP Request Type
Method name
Description

GET

ws_read

To retrieve data

POST

ws_create

To create new data

DELETE

ws_delete

To remove data

PUT

ws_update

To update data

PATCH

ws_patch

To partially update data

The RESTful Web Service endpoint is then available through the URL

{serverUrl}/servoy-service/rest_ws/{solutionName}/{name}.

Multiple endpoints can be created by implementing the relevant ws_* methods on multiple forms or scopes with the given {name}.

If the method for one of the HTTP Request Types is not implemented, that operation is not available on the endpoint and when attempted to be called a METHOD_NOT_ALLOWED (HTTP 405) error will be thrown.

The RESTful Web Service plugin does not have any client side functions or properties: all its magic happens by implementing the methods with the predefined ws_* names on a form.

Service Solution that has the web service implementation should be a Service type solution, this solution type should only be used for web service provider and batch processor.

Keeping It Stateless

  • Do not use global or form variables (or set them to default values at the end of the logic)

  • Do not use the solution model API

  • Do not alter the state of the form's UI

  • Do save or rollback any unsaved changes before the end of the method

Supporting GET Requests

GET requests are supported on the endpoint if the ws_read():Object method is implemented. The method can return either a JavaScript primitive/array/object, a byte array or a JSFile object. JSFile objects can be used to stream large files to the client.

If the return value of the method is null, a NOT_FOUND response (HTTP 404) will be generated.

Supporting POST Requests

POST requests are supported on the endpoint if the ws_create(content):Object method is implemented. POST Requests require that data is supplied in the body of the request.

The body content of the HTTP Request is passed into the ws_create() method as first argument. If the body Content-Type is not application/binary, it will be automatically converted to a JavaScript object / string.

If the body content cannot be converted to a JavaScript object / string based on the Content-Type, an INTERNAL_SERVER_ERROR response (HTTP 500) will be generated. If the content in the body of the HTTP Request is missing, a NO_CONTENT response will be generated (HTTP 204).

The ws_create() method supports consumption of multipart post requests. If the POST Request is a multipart POST, the content parameter will receive an Array of Objects, with each entry in the Array corresponding to one part of the multipart post, as per the example below:

Multipart post message
------WebKitFormBoundaryX6nBO7q27yQ1JNbb
Content-Disposition: form-data; name="myFileDescription"

My sample file content.
------WebKitFormBoundaryX6nBO7q27yQ1JNbb
Content-Disposition: form-data; name="myFile";
filename="SomeRandomFile.bin"
Content-Type: application/octet-stream

..... BINARY CONTENT.....
------WebKitFormBoundaryX6nBO7q27yQ1JNbb--
content parameter value
[
  {
    name:"myFileDescription",
    // bytes content is "My sample file."
    value: string, // before 2020.12
    contentType:"text/plain"
  },
  {
    name:"myFile",
    value:bytes[], // before 2020.12
    fileName:"SomeRandomFile.bin",
    contentType:"application/octet-stream"
  }
]
content parameter value
[
  // JSUpload in 2020.12 on previously it was a byte[] that behavior can be set back to byte[] by the property on the
  admin page for this plugin.
  // the extra data is in the JSUpload.getFields() and JSUpload.getFieldValue("myFileDescription") == "My sample file."
  {
    name:"myFile",
    value:JSUpload,
    fileName:"SomeRandomFile.bin",
    contentType:"application/octet-stream"
  }
]

The method can optionally return either a JavaScript primitive/array/object, a byte array or a JSFile object. JSFile objects can be used to stream large files to the client.

Supporting DELETE Requests

DELETE requests are supported on the endpoint if the ws_delete():Object method is implemented. The method can return various data types:

  • Boolean Values:

    • true: to indicate successful deletion. This result will generate an OK response (HTTP 200) unless a custom status has been set previously

    • false: to indicate delete failure. This response will generate a NOT_FOUND response (HTTP 404)

  • Other Return Types (JSON, String, Integer, etc.):

    • Any of these types returned by default will set the response to OK (HTTP 200) unless a custom status has been set previously. The response body will contain the returned data.

  • null / undefined :

    • This will set the response to OK (HTTP 200) unless a custom status has been set previously. The response body will be empty.

Supporting PUT Requests

PUT requests are supported on the endpoint if the ws_update(content):Boolean method is implemented. Data has to be supplied in the body of the HTTP request and the method has to return a Boolean value:

  • true: to indicate successful update. This result will generate an OK response (HTTP 200)

  • false: to indicate update failure. This response will generate a NOT_FOUND response (HTTP 404)

The body content of the HTTP Request is passed into the ws_update() method as first argument. If the body Content-Type is not application/binary, it will be automatically converted to a JavaScript object / string. The argument is the same as described above for POST.

If the body content cannot be converted to a JavaScript object / string based on the Content-Type an INTERNAL_SERVER_ERROR response (HTTP 500) will be generated. If the content in the body of the HTTP Request is missing, a NO_CONTENT response will be generated (HTTP 204).

Supporting PATCH Requests

PATCH requests are designed for partial updated (only certain fields). In the rest_ws plugin the ws_patch() method is called when implemented, the behaviour is the same as for PUT requests.

Additional arguments - when adding Extra Data to the Request URL or return values in ws_authenticate

Additional data can be added in the URL of the HTTP Requests. There are two variations and how they are made available in the ws_* methods differs.

Additional URL Fragments

The base URL for each operation is {serverUrl}/servoy-service/rest_ws/{solutionName}/{name}.

Additional URL fragments can be added to the URL like:

{serverUrl}/servoy-service/rest_ws/{solutionName}/{name}/{someValue}/{anotherValue}

The additional URL fragments {someValue} and {anotherValue} will be passed into the ws_* method as additional arguments. This means that for ws_read() and ws_delete() they will be the first and second argument and for ws_create() and ws_update() they will be the 2nd and 3rd argument, as these methods already have by default the content of the request as first argument.

Query Parameters

The request URLs can also be extended with Query parameters like:

{serverUrl}/servoy-service/rest_ws/{solutionName}/{name}?{someKey}={someValue}&{anotherKey}={anotherValue}&{anotherKey}={anotherValue2}

If the URL contains Query parameters, these will be passed into the ws_* method as an additional last argument. This last argument is a JavaScript object containing all keys as properties with the values associated with the key in an Array: Object<Array>

Combining Additional URL Fragments and Query Parameters

Additional URL path elements and Query parameters can be combined in the URL (the query parameters should come after the additional URL fragments to make it a valid URL):

{serverUrl}/servoy-service/rest_ws/{solutionName}/{name}/{someValue}/{anotherValue}?{someKey}={someValue}&{someKey}={anotherValue}&{anotherKey}={anotherValue2}

Example

An HTTP Get Request on URL

{serverUrl}/servoy-service/rest_ws/myRestAPISolution/APIv1/foo/bar?name=John&age=30&pet=Cat&pet=Dog

would result in invoking the ws_read method on form APIv1 of solution myRestAPISolution.

The ws_read function will be invoked with three parameters: 'foo', 'bar', {name: ['John'] , age: [30] , pet: ['Cat', 'Dog'] }

function ws_read()
{
  for (var i = 0; arguments.length, i++) {
    if (typeof arguments[i] == 'String') { // The URL path additions are passed in as Strings
     application.output('URL Path addition: ' + arguments[i])
    } else {
      for each (var key in arguments[i]) {
        application.output('Query Parameter "' + key + '", values:  "' + arguments[i][key].join(', ') + '"')
      }
    }
  }
}

// outputs:
// URL Path addition: foo
// URL Path addition: bar
// Query Parameter "name", values:  "John"
// Query Parameter "age", values:  "30"
// Query Parameter "pet", values:  "Cat, Dog"

Supported Content Types & Encoding

The plugin supports the following Content Types:

  • JSON - application/json

  • XML - application/xml

  • binary - application/binary

Request Content-Type and Encoding

The Content-Type of the HTTP Request can be explicitly set by the caller using the Content-Type header in the HTTP Request. Optionally, the charset can be included in the Content-Type header to specify the encoding used. If the charset is not specified, utf-8 will be assumed.

Content-Type Header

Content-Type: application/json; charset=utf-8

For requests that specify body content (POST and PUT Requests (resp. ws_create() and ws_update() methods)), if no valid Content-Type is set, the plugin will try to establish the type of the content based on the first character of the content:

  • '{': Content-Type application/json will be assumed

  • '<': Content-Type application/xml will be assumed

When the Content-Type cannot be determined, an UNSUPPORTED_MEDIA_TYPE response will be generated (HTTP 415).

Response Content-Type and Encoding

By default, the plugin will respond with the same content type as used in the HTTP Request. The client calling the RESTful Web Service can request a different response content type by specifying the desired content type for the Response by setting the Accept header of the HTTP Request, for example: Accept: application/json or Accept: application/binary

The response will be encoded with the utf-8 charset by default, if the response is not returning binary data.

If the encoding of the response needs to be different from the request encoding, this can be specified in the HTTP Request by setting the charset value in the Accept header:

Accept Header

Accept: application/json; charset=UTF-16

Returning Binary Data

The RESTful Web Services plugin supports returning binary data in the operations. Binary data could for example be the content of a dataprovider of type MEDIA or the contents of a file read from disk. In this case, the body of the response will contain the actual stream of bytes.

Clients consuming the web service must be able to handle the binary response. When the consuming client specifies the Accept header, it must accept application/binary, otherwise an UNSUPPORTED_MEDIA_TYPE (HTTP 415) response will be generated. If the consuming client did not specify the Content Type of the request, the binary result is returned unconditionally.

If you return large binary data, please use a JSFile wrapper around an actual file on disk, then the bytes are just streamed directly from disk to the client over the http request without the need to read the bytes fully in memory.

Setting Custom Headers

Custom headers can be set in the response by implementing the ws_response_headers() method. This method can return:

  • a string or an array of strings of type headerName=headerValue. For example Server=Servoy(Unix).

  • an object or an array of objects containing headerName/headerValue pairs. For example { name : "Content-Disposition", value : 'attachment; filename="test.txt"' } .

Each key/value pair will be added as Header to the HTTP Response.

Returning Custom Status Codes

While some of the HTTP Response status codes are hardcoded in the RESTful Webservices plugin, it is possible to control the HTTP Status codes from within the ws_* methods. Returning a custom HTTP Status Code can be done by throwing the specific value (a number) for the HTTP Status Code.

For example, when a ws_update call comes in for a non-existing resource, the HTTP Status Code to return would be a NOT_FOUND status code, which is an HTTP 404. Returning the 404/Not Found HTTP Status code from within a ws_* method could be done the following way:

function ws_update() {
  // your logic here
  throw plugins.http.HTTP_STATUS.SC_NOT_FOUND
}

It is also possible to set the body content of the HTTP Response with a more elaborate message to give more context to the returned status code:

function ws_update() {
  // your logic here
  var code = plugins.http.HTTP_STATUS.SC_UNAUTHORIZED
  var message = '<?xml version="1.0" encoding="UTF-8"?><error><reason>access denied</reason><message>access token is expired</message></error>'
  throw [code, message]
}

Authentication/Authorization

By default, access to any endpoint in unrestricted. The plugin supports 2 modes of implementing Authentication and authorization.

  1. Restricting access to all endpoints based on HTTP Basic Authentication, validated against Servoy's built-in security

  2. Restricting access per endpoint based on HTTP Basic Authentication with custom validation

Global Restrictions Based on Servoy Security

By setting the plugins server property rest_ws_plugin_authorized_groups to a comma separated list of groups defined in the built-in security system of Servoy, access to all endpoints is automatically restricted to users that are part of the groups in the list.

The endpoints must be called with HTTP Basic authentication to provide a username and password. The username/password supplied in the HTTP Request is validated against the users registered in Servoy's built-in security system and additionally against group membership. Access is denied if the user does not exist or the supplied password is incorrect, or the user doesn't belong to one of the specified groups.

When access is denied, an UNAUTHORIZED response is generated (HTTP 401).

Custom Endpoint Restrictions

For each endpoint custom authentication and authorization can be added by implementing the ws_authenticate(userName, password):Object method. If present, it will be called before performing any rest operation (ws_read, ws_create, ws_delete, ws_update) and the calls to the endpoint must be made with HTTP Basic Authentication to supply a username and password.

If the method returns false or null an UNAUTHORIZED response is generated (HTTP 401).

JSONP support

The plugin supports so-called JSONP: a variation of JSON that allows cross domain data retrieval. The JSONP variation can be invoked by added a callback parameter to the HTTP Request URL:

{serverUrl}/servoy-service/rest_ws/{solutionName}/{name}?callback={callbackFunctionName}

When invoked with the value myCallback for the callback parameter, the returned JSON value will be wrapped in a function call to the myCallback function:

myCallback({ "hello" : "Hi, I'm JSON. Who are you?"})

Versioning support

{serverUrl}/servoy-service/rest_ws/v2/mysolution/myform_or_scope/

or

{serverUrl}/servoy-service/rest_ws/mysolution/v2/myform_or_scope/

This is supported (the v has to be there and the 2 must be a number).

What is looked up is in the myform_v2 form or the scope_v2 scope (for version 2 of the api).

Nested call support

{serverUrl}/servoy-service/rest_ws/mysolution/myscope/mymethod/mymethod2/arg1

The plugin will now lookup in mysolution on the myscope scope a method named ws_read_mymethod_mymethod2; if that one is found it will call it with arg1 as an argument.

If ws_read_mymethod_mymethod2 method is not found it will try: ws_read_mymethod (that will then get 2 arguments: mymethod2 and arg1) and if that one is not found either it will fall back to ws_read (with 3 arguments).

Pool of Clients

To service the requests to the RESTful Web service API, the plugin creates a pool of (headless) clients. The maximum number of clients allowed can be set using the rest_ws_plugin_client_pool_size property of the plugin (default value = 5). If you have multiply rest solutions the property: rest_ws_plugin_client_pool_size_per_solution can be used to set the pool size per solution. This latter property will set the rest_ws_plugin_client_pool_size to -1. Because the max number will then be number of rest solutions multiplied by the per solution.

When there are more concurrent requests than the number of clients in the pool, by default the requests will wait until a client becomes available in the pool. This behavior can be altered by setting the rest_ws_plugin_client_pool_exhausted_action property of the plugin. The following values are supported for this property:

  • block (default): requests will wait until a client becomes available

  • fail: the request will fail. The API will generate a SERVICE_UNAVAILABLE response (HTTP 503)

  • grow: allows the pool to grow, by starting additional clients. This will set the 2 pool size properties to -1 (so voiding both of them). And if the rest_ws_plugin_client_pool_size_per_solution is set then that will be used as the number of idle clients to keep per solution.

Servoy Cluster

The RESTful Web service plugin uses a pool of headless clients to service the requests. When operated within a Servoy Cluster, note that poolsize is set per Servoy Application Server.

Client plugin

Code running inside a rest-ws request can access the request and the response using the rest_ws client plugin.

For example, retrieve a custom header sent by the client:

var request = plugins.rest_ws.getRequest()
var myheader = request.getHeader('My-Special-Header')

Note that the client-plugin can only be used within a request handler, the function plugins.rest_ws.isRunningRequest() can be used to check whether the code is running as a request hander.

Sample Solution

A sample solution is included in the Servoy distribution (servoy_sample_rest_ws.servoy), detailing how to retrieve data from the HTTP Request and to return a response.

More information on RESTful Web Services

See the following links for more information on RESTful Web Services:

PreviousScheduler APINextConsuming Webservices

Last updated 7 months ago

Was this helpful?

RESTful Web Services are to be . The RESTful Web Service plugin internally uses a pool of Headless Clients to handle multiple concurrent requests to the REStful Web Service API. As subsequent requests to the RESTful Web Service API might be handled by different headless clients in the pool of clients configured for the plugin, no state should be preserved in the headless client at the end of the call to the API. Therefore, make sure any state is cleared at the end of logic. This means at least the following:

If the return value is a JavaScript object, it will be serialized and then placed in the body of the HTTP Response. See for more info on returning binary content.

See what arguments you can receive in this method call at

If the return value is a JavaScript object, it will be serialized and then placed in the body of the HTTP Response. See for more info on returning binary content.

See what other arguments you can receive in this method call at

See what other arguments you can receive in this method call at

Note that if are implemented and the ws_authenticate() method returns any value but null or false, the RESTful Web Services plugin adds a query parameter with the key ws_authenticate and as value the returned value of the ws_authenticate() method.

For convenience purposes, all available HTTP Status Codes are also under the , so instead of throwing the number 404 in the first example, a more readable way would be to throw plugins.http.HTTP_STATUS.SC_NOT_FOUND

For additional explanation of all the status codes, see on Wikipedia.

Any other return value will be added as an extra query parameter (see ) with the key ws_authenticate to the incoming request.

Read more about method arguments at

See for the plugin.

stateless
List of HTTP status codes
http://en.wikipedia.org/wiki/Representational_State_Transfer
http://www.infoq.com/articles/rest-introduction
http://www.ibm.com/developerworks/webservices/library/ws-restful/
Returning Binary Data
Additional arguments
Returning Binary Data
Additional arguments
Additional arguments
Custom Endpoint Restrictions
Additional arguments
Additional arguments
API documentation
Servoy rest_ws plugin
listed
HTTP Plugin