بناء تطبيقات REST API

توفر IRIS دعم مدمجاً لبناء REST APIs عبر %CSP.REST.

Class MyApp.API.REST Extends %CSP.REST {
  XData UrlMap {
    
      
    
  }
  ClassMethod GetEmployees() As %Status {
    Set result = []
    Set rs = ##class(%SQL.Statement).%ExecDirect(,"SELECT ID,Name FROM Employee")
    While rs.%Next() {
      Do result.%Push({"id":(rs.%Get("ID")),"name":(rs.%Get("Name"))})
    }
    Write result.%ToJSON()
    Return $$$OK
  }
}

التعامل مع JSON أمر أساسي في APIs.

Method EmployeeToJSON(emp) {
  Set json = {}
  Set json.id = emp.%Id()
  Set json.name = emp.Name
  Return json
}

تأمين REST APIs أمر حاسم.

Parameter SECURITYRESOURCE = "MyAPI:RW";
ClassMethod OnPreDispatch() As %Status {
  If '$System.Security.Check("MyAPI:RW","WRITE") {
    Set %response.Status = 403
    Return $$$ERROR(5001,"Forbidden")
  }
  Return $$$OK
}

معالجة الأخطاء بشكل صحيح في APIs أمر حاسم لتجربة مستخدم جيدة.

// معالجة أخطاء موحدة
ClassMethod HandleError(status As %Status) {
  Set %response.Status = 500
  Set error = {
    "error": "Internal Server Error",
    "message": ($System.Status.GetErrorText(status)),
    "timestamp": ($ZDT($H,3))
  }
  Write error.%ToJSON()
}

// استخدام HTTP Status Codes
// 200 - نجاح
// 201 - تم الإنشاء
// 400 - طلب خاطئ
// 401 - غير مصرح
// 404 - غير موجود
// 500 - خطأ داخلي

ل APIs التي تُرجع قوائم كبيرة، يجب استخدام Pagination.

ClassMethod GetEmployees(page As %Integer = 1, size As %Integer = 10) As %Status {
  Set offset = (page - 1) * size
  Set sql = "SELECT ID, Name, Department FROM Employee "
  Set sql = sql _ "ORDER BY ID LIMIT " _ size _ " OFFSET " _ offset
  
  Set rs = ##class(%SQL.Statement).%ExecDirect(, sql)
  Set result = {"data": [], "page": (page), "size": (size)}
  
  While rs.%Next() {
    Do result.data.%Push({
      "id": (rs.%Get("ID")),
      "name": (rs.%Get("Name")),
      "department": (rs.%Get("Department"))
    })
  }
  
  // إجمالي السجلات
  &sql(SELECT COUNT(*) INTO :total FROM Employee)
  Set result.total = total
  Set result.pages = $Number(total / size, 0, 1)
  
  Write result.%ToJSON()
  Return $$$OK
}