I configured APIM logger to EventHub using article
https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-log-event-hubs
In the example some of the fields are given viz.
DateTime.UtcNow, context.Deployment.ServiceName, context.RequestId, context.Request.IpAddress
I want to configure more like who is referrer, result, time etc.
Where I can find complete list of the fields?
Valid types allowed in policy expressions are listed here https://learn.microsoft.com/en-us/azure/api-management/api-management-policy-expressions.
I am wondering if implicitly using the currently authenticated user as context for API interactions is RESTful or not. For example, assuming all my API calls are authenticated using standard HTTP security:
Should a query to retrieve a list of orders for the user be explicit?
NO: http://example.com/orders
YES: http://example.com/orders?userid=1234
When placing a POST to create a new order, should the JSON contain the user?
NO: { orderref: 'EXAM/1', items: { ... } }
YES: { userid: 1234, orderref: 'EXAM/1', items: { ... } }
Either way I'll be securing so that the API will only allow actions for the current user, but should I make the API caller state the userid for each action?
I would say you should only pass the user ID as a query if you have access to many user's orders and need to filter them by user.
If a user has access to only their own orders they should not have to pass a user ID - the base queryset should limit it based on their own authentication details. Arguably that may not be RESTful, but don't worry about that - most API's may not be 100% RESTful and you should do what makes sense for your application rather than worrying about whether it's RESTful - it's a guide, not a cast-iron requirement.
In any case depending on what type of authentication you use (BASIC or TOKEN), you have to send the user info in your API call (Headers) which makes the request to the API.
So when you say if it is valid to use the authenticated user from the Context, of course it is
sample code here
The api call
headers.Authorization = 'Bearer ' + localStorage.getItem("tokenkey");
Obtain user from the request
RequestContext.Principal.Identity.Name
Is it RESTful? I would argue that: yes it is. There is no REST spec, so there's nothing really that says that it isn't. HTTP does allow this, and HTTP Caches should actually by default consider responses to GET requests with an Authorization header as private.
Should you use this design? I don't know! I think there's benefits to having per-user endpoints, because in the future it might allow User A to inspect the orders of User B.
In our API we actually have an example of an API similar to yours, but we do both.
We have a /users/1234 endpoint.
We also have a /current-user endpoint.
Initially the /current-user endpoint just redirected to the uri of the actual current user, but eventually we decided we're actually just going to return the full object without redirecting (due to browsers not behaving nicely with redirects).
The current-user endpoint does have a self link still that points to the real user resource.
So to sum it up. I think you are in the clear here, but I argue that there are strong design benefits to creating resources that have a consistent representation regardless of who's looking at it. It makes things a bit simpler and nicer.
And also don't forget that there's no reason why you can't, if you are actually following REST. All a client should care about is that there's a link somewhere to a list of orders and it shouldn't care what it's url is.
+1 for Matthew Daly's answer. Especially when the authenticated user has only access to his own orders (I assume that).
In case that your authenticated user can access more order lists than only his own, I would go like that:
/orders: the authenticated user's orders.
/orders/123: the specific user's orders.
If 123 equals the authenticated user's id - so what? It would be most likely no problem case for your client.
By designing a REST service you think of the comfort that the developers could have, when they use your API. I would say, this one is a comfortable solution.
Should a query to retrieve a list of orders for the user be explicit?
NO: http://example.com/orders
YES: http://example.com/orders?userid=1234
When placing a POST to create a new order, should the JSON contain the
user?
NO: { orderref: 'EXAM/1', items: { ... } }
YES: { userid: 1234, orderref: 'EXAM/1', items: { ... } }
If user queries only its own orders, user id shouldn't be passed explicitly in the query - you should pass user token in HTTP header and your code should extract user id by provided token and determine whether authorized user has rights to see or modify particular data.
In case you want to let one user get or modify another user data then you would make additional endpoint - something like users/{userId}/orders or users/{userId}/orders/{orderId}. You would still pass user token via HTTP header and your implementation should check if user has admin rights for this action.
I need to store the values of devices' attributes with the right type in OrionCB's MongoDB.
As I was unable to perform that I dived into the code and found that IoTAgentUL (as well as IoTAgentJSON) uses OrionCB's API v1 instead of API v2.
As I can see API v1's updateContext sends data to MongoDB without it's type, so every measure is stored as text.
In the other hand I found that API v2's update entity send data to MongoDB with it's type. It produces that I can store attribute's values with it's type which benefits me when manipulating data (i.e. creating indexes, sorting, etc).
My question is if is there any workaround to solve this using the current implementations of IoT Agents.
The only workaround I can imagine is, once entities are automatically created by the IoT Agents, to update the type of such entities by your own. I mean, AFAIK, you can update both the value and the type of an entity.
In more details, I can think on a script that subscribes for all entities of certain type (those created by the agents). Then, when an entity is created this is notified to the script, which automatically updates the type of the entity's attributes.
Please observe you only need to modify the attribute's types once, just when the entities are created, not when an entity's attribute is updated; thus, something like an array or cache of already modified entities is needed in your script.
I am doing an analysis of Credit Union social activity. I have some code that takes a link like this...
https://www.facebook.com/americanlakecu/likes
... and converts it to this...
http://graph.facebook.com/americanlakecu
..which enables me to grab 'Likes' and 'People Talking'. The problem is many institutions, particularly the smaller ones, seem to use a different format. Here's an example.
https://www.facebook.com/pages/EvergreenDIRECT-Credit-Union/276887662722?sk=likes
Anyone know how to convert the link above so I can use the api to render JASON in the same way as http://graph.facebook.com/americanlakecu ?
You need to reference the facebook id when hitting the graph for the other institutions. For americanlakecu, that id is americanlakecu. For Evergreen's case, try 276887662722. But for some reason, your "smaller" pages need an access token. I think the difference might be a simple matter of availability of data.
You can still get their data as I described above, but you need an api access token. For instance, following this link directly will show you nothing: http://developers.facebook.com/tools/explorer/?method=GET&path=276887662722 , but after you get there, if you fetch an access token, you will see all the info you need.
So, configure your implementation of the SDK to use an access token, and you ought to be able to continue using the handy graph method.
What are REST resources and how do they relate to resource names and resource representations?
I read a few articles on the subject, but they were too abstract and they left me more confused than I was before.
Is the following URL a resource? If it is, what is the name of that resource and what is its representation?
http://api.example.com/users.json?length=2&offset=5
The GET response of the URL should look something like:
[
{
id: 6,
name: "John"
},
{
id: 7,
name: "Jane"
}
]
The reason why articles on REST resources are abstract is because the concept of a REST resource is abstract. It's basically "whatever thing is accessed by the URL you supply". So, in your example, the resource would be the list of two users starting at offset 5 in some bigger list. Note that, how the resource is implemented is a detail you don't care about unless you are the one writing the implementation.
Is the following URL a resource?
The URL is not a resource, it is a label that identifies the resource, it is, if you like, the name of the resource.
The JSON is a representation of the resource.
What’s a Resource?
A resource is anything that’s important enough to be referenced as a
thing in itself. If your users might “want to create a hypertext link
to it, make or refute assertions about it, retrieve or cache a
representation of it, include all or part of it by reference into
another representation, annotate it, or perform other operations on
it”, then you should make it a resource.
Usually, a resource is something that can be stored on a computer and
represented as a stream of bits: a document, a row in a database, or
the result of running an algorithm. A resource may be a physical
object like an apple, or an abstract concept like courage, but (as
we’ll see later) the representations of such resources are bound to be
disappointing. Here are some possible resources:
Version 1.0.3 of the software release
The latest version of the software release
The first weblog entry for October 24, 2006
A road map of Little Rock, Arkansas
Some information about jellyfish
A directory of resources pertaining to jellyfish
The next prime number after 1024
The next five prime numbers after 1024
The sales numbers for Q42004
The relationship between two acquaintances, Alice and Bob
A list of the open bugs in the bug database
The text is from the O'Reilly book "RESTful Web Services".
The URL is never a resource or its name or its representation.
URL just tells where the resource is located and You can invoke GET,POST,PUT,DELETE etc on this URL to invoke the resource.
Data responded back are the resources while the form of the data is its representation.
Let's say Your URL with given GET parameters can output a JSON resource - this is the JSON representation of this resource. While with other flag in the GET it could respond with the same data in XML - that will be another representation of the very same resource.
EDIT: Due to the comments to the OP and to my answer I'm adding another explanations.
Also the resource name is considered to be the 'script name', e.g. in this case it is users.json while this resource name is self describing the resource representation itself - when calling this resource we expect the resource is in JSON, while when calling e.g. users.xml we would expect the data in XML.
When I change the offset parameter in GET the response contains
different data set - is it a new resource or its representation?
When I define which columns are returned in response in GET, is it a different resource or different representation, or?
Well, here the problem and answer are clear - we still call the same URL, the server responses with the data in the same form (still it is JSON), data still contains information about users - just the information itself has changed due to the new offset parameter. So it is obvious that it is still the same resource with the same representation and the same resource name as before.
Second problem could be a little confusing. Though we are calling the same resource, though the resource contains the same data (just with only predefined column set) and though the data is in the same representation it could seem to us as a different resource. But due to the points in the paragraph above it is nor the different resource or different representation. Though the data set contains less information the requesting side (filtering this data set) should be considering this and behave accordingly. So again: it is the same resource with the same resource name and the same resource representation.
REST
This architectural style was defined in the chapter 5 of Roy T. Fielding's dissertation.
REST is about resource state manipulation through their representations on the top of stateless communication between client and server. It's a protocol independent architectural style but, in practice, it's commonly implemented on the top of the HTTP protocol.
Resources
The resource itself is an abstraction and, in the words of the author, a resource can be any information that can be named. The domain entities of an application (e.g. a person, a user, a invoice, a collection of invoices, etc) can be resources. See the following quote from Fielding's dissertation:
5.2.1.1 Resources and Resource Identifiers
The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.
More precisely, a resource R is a temporally varying membership function MR(t), which for time t maps to a set of entities, or values, which are equivalent. The values in the set may be resource representations and/or resource identifiers. [...]
Resource representations
A JSON document is resource representation that allows you to represent the state of a resource. A server can provide different representations for the same resource. For example, using XML and JSON documents. A client can use content negotiation to request different representations of the same resource.
Quoting Fielding's dissertation:
5.2.1.2 Representations
REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components. A representation is a sequence of bytes, plus representation metadata to describe those bytes. Other commonly used but less precise names for a representation include: document, file, and HTTP message entity, instance, or variant.
A representation consists of data, metadata describing the data, and, on occasion, metadata to describe the metadata (usually for the purpose of verifying message integrity). Metadata is in the form of name-value pairs, where the name corresponds to a standard that defines the value's structure and semantics. Response messages may include both representation metadata and resource metadata: information about the resource that is not specific to the supplied representation. [...]
Over HTTP, request and response headers can be used to exchange metadata about the representation.
Resource identifiers
A URL a resource identifier that identifies/locates a resource in the server.
This answer may also be insightful.
What are REST resources and how do they relate to resource names and resource representations?
REST doesn't mean a great deal more then you use HTTP verbs (GET, POST, PUT, DELETE, etc) properly.
Is the following URL a resource?
All URLs are strings that tell computers where a resource can be located. (Hence the name: Uniform Resource Locator).
A resource is:
a noun
that is unique
and can be represented as data
and has at least one URI
I go into more detail on my blog post, What, Exactly, Is a RESTful Resource?
Representational State Transfer (REST) is a style of software architecture for distributed systems such as the World Wide Web. REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources. Resources are a set of addressable objects, basically files and documents, linked using URLs. As correctly pointed out above by Quentin, REST archiecture simply implies that you'd use the HTTP verbs GET/POST/PUT/DELETE...
Conceptually you can think about a resource as everything which is accessible on the web using an URL.
If you stick to this rule http://api.example.com/users.json?length=2&offset=5 can be considered a resource
You've only provided what appear to be relative parameters rather than "ID" which is (or should be) concrete. Remember, get operations should be idempotent (i.e. repeatable with the same outcome).
What is REST?
REST is an architecture Style which stands for Representational(RE) State(S) transfer(T).
What is REST Resource ?
Rest Resource is data on which we want to perform operation(s).So this data can be present in database as record(s) of table(s) or in any other form.This record has unique identifier with which it can be identified like id for Employee.
Now when this data is requested by unique url like http://www.example.com/employees/123,so ultimately data or record which is present in database will be converted to JSON/XML/Plain text format by Rest Service and will be sent to Consumer.
So basically,what is happening here is REPRESENTATIONAL STATE TRANSFER, in a way that state of the data present in database is transferred to another format which can be JSON/XML or plain text.
So in this case 1 employee represents 1 resource which can be accessed by unique url like http://www.example.com/employees/123
In case we want to get list of all resources(employees),we will do:
http://www.example.com/employees
Hope this will help.
REST stands for REpresentational State Transfer. It's a method of transferring variable information from one location to another. A common method of doing this is using JSON - a way of formatting your variables so that they can be transferred without loss of information.
PHP, for example, has built in JSON support. Passing a PHP array to json_encode($array) will output a string in the format you posted (which by the way, is indeed a REST resource, because it gives you variables and information).
In PHP, the array you posted would turn out as:
Array (
[0]=>Array (
['id']=>6;
['name']=>'John';
)
[1]=>Array (
['id']=>7;
['name']=>'Jane';
)
)